Generate Clarification Questions

Generate AI-powered clarification questions to refine criteria for a job

POST /v1/jobs/{jobId}/question-sets

@nova-sdk/api

TypeScript

import { Nova } from "@nova-sdk/api";

const nova = new Nova({
  apiKey: "sk_test_...",
  tenantId: "acme-corp",
});

const result = await nova.jobs.questionSets.create({
  jobId: "job_abc123",
  body: {
    jobContext: {
      jobTitle: "Senior Software Engineer",
      companyName: "Acme Corp",
      jobDescription: "We are looking for a senior engineer...",
    },
  },
});

201

{
  "questionSet": {
    "id": "<string>",
    "jobId": "<string>",
    "questions": [
      {
        "id": "<string>",
        "question": "<string>",
        "options": [
          "<string>"
        ],
        "hint": "<string>"
      }
    ],
    "expiresAt": "2023-11-07T05:31:56Z",
    "guidance": "<string>"
  }
}

Optional but recommended. Answers to these questions produce better criteria.

Selection Types

Selection Type	Description	Answer Format
single	Choose one option (radio buttons)	string
multi	Choose multiple options (checkboxes)	string[]

Example Questions

Single Select

{
  "id": "q1",
  "selectionType": "single",
  "question": "What level of seniority are you targeting?",
  "options": [
    "Junior (0-2 years)",
    "Mid (2-5 years)",
    "Senior (5+ years)",
    "Lead/Staff"
  ],
  "hint": "Helps calibrate experience requirements"
}

Multi Select

{
  "id": "q2",
  "selectionType": "multi",
  "question": "Which skills are absolutely required vs nice-to-have?",
  "options": ["Go", "Rust", "Python", "Kubernetes", "AWS"],
  "hint": "Helps distinguish MUST_HAVE from NICE_TO_HAVE"
}

Stateful Behavior

Store the questionSetId to reference this question set later. If you don’t, fetch the latest via GET /v1/jobs/{jobId}/question-sets/current.

Each call creates a new question set. Multiple sets can exist for the same job.

Question sets expire. Check questionSet.expiresAt for the expiration time. Expired question sets are cleaned up per the Data Retention policy.

Latency

10-20 seconds (synchronous).

Next Step

After collecting answers, pass the questionSetId and answers to Generate Criteria.

Authorizations

Authorization · string · header · required

Use Authorization: Bearer sk_test_* or Authorization: Bearer sk_live_*.

Headers

X-Tenant-Id · string · required

Your customer identifier. Tenants are auto-provisioned on first request.

Idempotency-Key · string

Optional key that makes criteria and library mutation requests safe to retry without duplicating side effects. The namespace is shared across all API keys for the same partner and environment. Reuse the same key when retrying the same request parameters.

Required string length: 1 - 255

Path Parameters

jobId · string · required

Your job identifier (external ID).

Body

application/json

jobContext · object · required

Show child attributes

Response

201

application/json

Created

questionSet · object · required

Show child attributes