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>",
        "selectionType": "single",
        "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.

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.

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