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

​
Prerequisites

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

​
Step 1: Generate Clarification Questions (Optional)

First, generate clarification questions. This step is optional but recommended for better criteria calibration. 
curl -X POST https://embed.nova.dweet.com/v1/criteria/questions \
  -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": "We are looking for a Senior Software Engineer with 5+ years of experience in backend development. Strong proficiency in Go or Python required. Experience with Kubernetes and cloud infrastructure preferred."
    }
  }'
Response: 
{
  "questionSetId": "qs_abc123def456",
  "questions": [
    {
      "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", "Python", "Kubernetes", "AWS", "Docker"],
      "hint": "Helps distinguish MUST_HAVE from PREFERRED criteria"
    }
  ],
  "guidance": "These questions will help calibrate the screening criteria."
}
Store the questionSetId - you’ll need it when generating criteria with your team’s answers.

​
Step 2: Generate Criteria

Generate screening criteria from your job description, optionally including your team’s answers: Response: 
{
  "jobId": "job-123",
  "criteria": [
    {
      "id": "crit_abc123",
      "text": "5+ years of professional software engineering experience",
      "importance": "MUST_HAVE"
    },
    {
      "id": "crit_def456",
      "text": "Strong proficiency in Go for backend development",
      "importance": "MUST_HAVE"
    },
    {
      "id": "crit_ghi789",
      "text": "Experience with Kubernetes and container orchestration",
      "importance": "PREFERRED"
    }
  ],
  "status": "active",
  "createdAt": "2025-01-15T10:00:00Z"
}

​
Step 3: Score a Candidate

When a candidate applies, submit their resume for scoring. Notice how simple this is - just the job ID, application ID, and resume: 
curl -X POST https://embed.nova.dweet.com/v1/score \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "X-Tenant-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": "job-123",
    "applicationId": "app-456",
    "candidate": {
      "resumeUrl": "https://your-storage.com/resumes/candidate-123.pdf?token=..."
    }
  }'
Response (202 Accepted): 
{
  "scoringJobId": "sj_abc123def456",
  "status": "queued",
  "estimatedCompletionSeconds": 30
}

​
Step 4: Receive Results

Results are delivered via webhook to your configured endpoint:
Webhook Payload
{
  "event": "score.completed",
  "scoringJobId": "sj_abc123def456",
  "jobId": "job-123",
  "applicationId": "app-456",
  "result": {
    "score": 7,
    "assessment": {
      "verdict": "Strong candidate with solid backend experience. Meets core requirements but lacks direct Kubernetes experience. Recommend proceeding to technical interview.",
      "strengths": [
        "6 years of backend engineering experience at high-growth startups",
        "Strong Go proficiency demonstrated through open-source contributions"
      ],
      "concerns": [
        "No direct Kubernetes experience; container orchestration exposure is limited"
      ],
      "interviewFocus": [
        "Probe depth of distributed systems knowledge",
        "Assess willingness and ability to learn Kubernetes quickly"
      ]
    }
  },
  "completedAt": "2025-01-15T10:30:45Z"
}
If you miss the webhook, you can retrieve results using GET /v1/score/{scoringJobId}.

​
What’s Next?

Webhook Setup

Configure and verify webhook delivery

Criteria Management

View, update, and manage criteria

Integration Flow

Complete implementation guide

Full API Reference

Explore all endpoints in detail