Generate Clarification Questions

Generate clarification questions

curl --request POST \
  --url https://embed.nova.dweet.com/v1/criteria/questions \
  --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"
  }
}
'

{
  "questionSetId": "<string>",
  "questions": [
    {
      "id": "<string>",
      "type": "singleSelect",
      "question": "<string>",
      "options": [
        "<string>"
      ],
      "placeholder": "<string>",
      "hint": "<string>"
    }
  ],
  "guidance": "<string>"
}

POST

criteria

questions

Generate clarification questions

curl --request POST \
  --url https://embed.nova.dweet.com/v1/criteria/questions \
  --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"
  }
}
'

{
  "questionSetId": "<string>",
  "questions": [
    {
      "id": "<string>",
      "type": "singleSelect",
      "question": "<string>",
      "options": [
        "<string>"
      ],
      "placeholder": "<string>",
      "hint": "<string>"
    }
  ],
  "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 PREFERRED)
Clarify ambiguous requirements in the job description
Capture context that isn’t in the written job description

Workflow

Question Types

The API returns three types of questions:

Type	Description	Answer Format
`singleSelect`	Choose one option	`string`
`multiSelect`	Choose multiple options	`string[]`
`text`	Free-form text input	`string`

Example Questions

Single Select
Multi Select
Text

{
  "id": "q1",
  "type": "singleSelect",
  "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"
}

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

{
  "id": "q3",
  "type": "text",
  "question": "Any specific context about the team or role?",
  "placeholder": "e.g., team size, working style, growth plans",
  "hint": "Additional context improves criteria quality"
}

Storing the Question Set ID

Always store the questionSetId returned by this endpoint. You’ll need it when calling /v1/criteria/generate with answers.

const response = await fetch('/v1/criteria/questions', {
  method: 'POST',
  headers: { ... },
  body: JSON.stringify({ jobContext: { ... } }),
});

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

// 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.

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

API key authentication. Use your environment-specific API key (sk_test_* for sandbox, sk_live_* for production).

Headers

X-Tenant-Id

string

required

Your customer/tenant identifier. Used for data isolation and per-customer metrics. Tenants are created automatically on first request.

Body

application/json

jobContext

object

required

Show child attributes

jobContext.jobId

string

required

Your job ID (echoed back in responses)

jobContext.jobTitle

string

required

The title of the job posting

jobContext.companyName

string

required

The name of the hiring company

jobContext.jobDescription

string

required

Full job description (HTML or plain text)

jobContext.additionalInfo

string

Optional context such as internal notes, team info, or additional requirements

jobContext.applicationQuestions

object[]

Application questions in any format - we'll extract relevant information

jobContext.language

string

default:English

Language for generated output

Response

Clarification questions generated successfully

questionSetId

string

required

Unique identifier for this question set. Store this to submit answers.

questions

object[]

required

Clarification questions to present to your team

Show child attributes

questions.id

string

required

Unique identifier for this question

questions.type

enum<string>

required

Question type determining the expected answer format

Available options:

singleSelect,

multiSelect,

text

questions.question

string

required

The question text to display

questions.options

string[]

Available options (required for singleSelect and multiSelect types)

questions.placeholder

string

Placeholder text for text input (text type only)

questions.hint

string

Helpful context about why this question is asked

guidance

string

Human-readable explanation of why these questions help

Criteria Management Generate Criteria

⌘I

Getting started

Core concepts

API endpoints

Integration guides

Generate Clarification Questions

When to Use

Workflow

Question Types

Example Questions

Storing the Question Set ID

Stateful Behavior

Latency

Next Step

Authorizations

Headers

Body

Response

Getting started

Core concepts

API endpoints

Integration guides

​When to Use

​Workflow

​Question Types

​Example Questions

​Storing the Question Set ID

​Stateful Behavior

​Latency

​Next Step

Authorizations

Headers

Body

Response

When to Use

Workflow

Question Types

Example Questions

Storing the Question Set ID

Stateful Behavior

Latency

Next Step