Skip to main content
POST
/
v1
/
jobs
/
{jobId}
/
question-sets
Generate a question set
curl --request POST \
  --url https://embed.nova.dweet.com/v1/jobs/{jobId}/question-sets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Id: <x-tenant-id>' \
  --data '
{
  "jobContext": {
    "jobId": "<string>",
    "jobTitle": "<string>",
    "companyName": "<string>",
    "jobDescription": "<string>",
    "additionalInfo": "<string>",
    "applicationQuestions": [
      {}
    ],
    "language": "English"
  }
}
'
{
  "questionSet": {
    "id": "<string>",
    "jobId": "<string>",
    "questions": [
      {
        "id": "<string>",
        "question": "<string>",
        "selectionType": "single",
        "options": [
          "<string>"
        ],
        "hint": "<string>"
      }
    ],
    "expiresAt": "2023-11-07T05:31:56Z",
    "guidance": "<string>"
  }
}
This endpoint is optional but recommended. Clarification questions help your team refine the criteria, resulting in better candidate-job matching.

​
When to Use

Use this endpoint when you want to:
  • Help your team calibrate importance levels (MUST_HAVE vs NICE_TO_HAVE)
  • Clarify ambiguous requirements in the job description
  • Capture context that isn’t in the written job description

​
Workflow

​
Selection Types

Questions have a selectionType that determines how answers should be collected:
Selection TypeDescriptionAnswer Format
singleChoose one option (radio buttons)string
multiChoose multiple options (checkboxes)string[]

​
Example Questions

{
  "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"
}

​
Storing the Question Set ID

Store the questionSetId if you need to reference this question set later. If you do not store it, you can fetch the latest question set for a job via GET /v1/jobs/{jobId}/question-sets/current.
const response = await fetch(`https://embed.nova.dweet.com/v1/jobs/${jobId}/question-sets`, {
  method: 'POST',
  headers: { ... },
  body: JSON.stringify({ jobContext: { ... } }),
});

const { questionSet } = await response.json();
const questionSetId = questionSet.id;
const questions = questionSet.questions;

// Store questionSetId with your job posting
await db.jobPosting.update({
  where: { id: jobId },
  data: { novaQuestionSetId: questionSetId },
});

// Present questions to your team
showQuestionsUI(questions);

​
Stateful Behavior

Each call creates a new question set with a unique questionSetId. Multiple question sets can exist for the same job if you regenerate questions.
Question sets expire. Use questionSet.expiresAt to know when the question set is no longer valid.
This allows you to:
  • Regenerate questions if the job description changes
  • Keep historical records of questions asked
  • Support multiple drafts before finalizing criteria

​
Latency

10-20 seconds (synchronous) The AI analyzes the job description to generate contextually relevant questions. This is a one-time operation per job posting.

​
Next Step

After collecting answers, proceed to Generate Criteria with the questionSetId and answers.

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

Response

Created

​
questionSet
object
required