Skip to main content
This guide walks you through a complete flow: generate clarification questions, generate criteria for a job, and submit a candidate for scoring.

​
Prerequisites

API key from the Embed Portal (sk_test_* for sandbox)
A tenant ID (your customer identifier)

​
Step 1: Generate clarification questions (optional)

curl -X POST 'https://embed.nova.dweet.com/v1/jobs/job-123/question-sets' \
  -H 'Authorization: Bearer sk_test_your_key' \
  -H 'X-Tenant-Id: acme-corp' \
  -H 'Content-Type: application/json' \
  -d '{
    "jobContext": {
      "jobId": "job-123",
      "jobTitle": "Senior Software Engineer",
      "companyName": "Acme Corp",
      "jobDescription": "..."
    }
  }'
Response: 
{
  "questionSet": {
    "id": "question_set_id",
    "jobId": "job-123",
    "questions": [
      {
        "id": "q1",
        "type": "SINGLE_SELECT",
        "question": "What level of seniority are you targeting?",
        "options": ["Junior", "Mid", "Senior"]
      }
    ],
    "guidance": "Answer these questions to calibrate criteria generation.",
    "expiresAt": "2025-12-14T11:30:45Z"
  }
}
Store questionSet.id. You will use it in the next step.

​
Step 2: Generate criteria

curl -X POST 'https://embed.nova.dweet.com/v1/jobs/job-123/criteria-generations' \
  -H 'Authorization: Bearer sk_test_your_key' \
  -H 'X-Tenant-Id: acme-corp' \
  -H 'Content-Type: application/json' \
  -d '{
    "jobContext": {
      "jobId": "job-123",
      "jobTitle": "Senior Software Engineer",
      "companyName": "Acme Corp",
      "jobDescription": "..."
    },
    "questionSetId": "question_set_id",
    "answers": [
      { "id": "q1", "type": "SINGLE_SELECT", "value": "Senior" }
    ]
  }'

​
Step 3: Submit a score request

curl -X POST 'https://embed.nova.dweet.com/v1/jobs/job-123/applications/app-456/scoring-jobs' \
  -H 'Authorization: Bearer sk_test_your_key' \
  -H 'X-Tenant-Id: acme-corp' \
  -H 'Content-Type: application/json' \
  -d '{
    "resumeUrl": "https://storage.example.com/resumes/abc123.pdf"
  }'
Response: 
{
  "scoringJob": {
    "id": "scoring_job_id",
    "status": "PENDING"
  }
}

​
Step 4: Receive results

Use webhooks for real-time delivery. Use polling as a fallback:
  • Webhooks: Webhooks
  • Polling: GET /v1/jobs/{jobId}/applications/{applicationId}/scoring-jobs/{scoringJobId} via Get scoring job