Score Candidate

Submit a candidate for AI-powered scoring. Criteria are automatically loaded from your stored criteria for this job - you don’t need to pass them. This is an asynchronous operation with results delivered via webhook.

How It Works

Request

{
  "jobId": "job-123",
  "applicationId": "app-456",
  "candidate": {
    "resumeUrl": "https://storage.example.com/resumes/abc123.pdf?token=xyz&expires=1705312800"
  }
}

Notice there’s no criteria field - Nova automatically uses the criteria you generated for this job via POST /v1/criteria/generate.

Prerequisites

Before scoring candidates, you must have active criteria for the job:

// First, generate criteria for the job (once per job)
await fetch('https://embed.nova.dweet.com/v1/criteria/generate', {
  method: 'POST',
  headers: { ... },
  body: JSON.stringify({
    jobContext: {
      jobId: 'job-123',
      jobTitle: 'Senior Software Engineer',
      companyName: 'Acme Corp',
      jobDescription: '...',
    },
  }),
});

// Then score candidates - criteria are loaded automatically
await fetch('https://embed.nova.dweet.com/v1/score', {
  method: 'POST',
  headers: { ... },
  body: JSON.stringify({
    jobId: 'job-123',
    applicationId: 'app-456',
    candidate: {
      resumeUrl: 'https://...',
    },
  }),
});

If no active criteria exist for the job, the request will fail with CRITERIA_NOT_FOUND. Generate criteria first using /v1/criteria/generate.

Request Requirements

Resume URL

The resumeUrl must be:

Pre-signed: Accessible without authentication
Valid for 2+ hours: We recommend 24 hours for safety
HTTPS: HTTP URLs are not accepted

"candidate": {
  "resumeUrl": "https://storage.example.com/resumes/abc123.pdf?token=xyz&expires=1705312800"
}

See Supported Formats for accepted file types.

Optional: Parsed Resume

If you have structured resume data, include it to improve accuracy:

"candidate": {
  "resumeUrl": "https://...",
  "parsedResume": {
    "name": "Jane Smith",
    "experience": [
      {
        "title": "Senior Engineer",
        "company": "Tech Corp",
        "duration": "2019-2024"
      }
    ],
    "skills": ["Go", "Python", "Kubernetes"]
  }
}

Optional: Application Answers

Include application Q&A for additional context:

"candidate": {
  "resumeUrl": "https://...",
  "applicationAnswers": {
    "workAuthorization": "Yes, I am authorized to work in the UK",
    "startDate": "Immediately available",
    "salaryExpectations": "80,000 - 100,000"
  }
}

Idempotency

The scoring endpoint is idempotent by default. Duplicate requests (same jobId + applicationId) return the existing job instead of creating a new one.

This makes retries safe. To bypass idempotency (e.g., after updating criteria), use the rescore parameter. See Idempotency for details.

Response

{
  "scoringJobId": "sj_abc123def456",
  "status": "queued",
  "estimatedCompletionSeconds": 30
}

Store the scoringJobId to:

Correlate with incoming webhooks
Poll for results if needed
Debug issues with support

Processing Time

Stage	Duration
Queue wait	Typically < 5 seconds
Processing	20-30 seconds
Total	~30 seconds

What Happens Next

Results arrive via webhook:

Success
Failure

{
  "event": "score.completed",
  "scoringJobId": "sj_abc123def456",
  "jobId": "job-123",
  "applicationId": "app-456",
  "result": {
    "score": 7,
    "assessment": {
      "verdict": "Strong candidate with solid backend experience...",
      "strengths": ["6 years of backend engineering experience"],
      "concerns": ["No direct Kubernetes experience"],
      "interviewFocus": ["Probe depth of distributed systems knowledge"]
    }
  },
  "completedAt": "2025-01-15T10:30:45Z"
}

{
  "event": "score.failed",
  "scoringJobId": "sj_abc123def456",
  "jobId": "job-123",
  "applicationId": "app-456",
  "error": {
    "code": "RESUME_FETCH_FAILED",
    "message": "Failed to fetch resume: URL expired"
  },
  "failedAt": "2025-01-15T10:30:15Z"
}

Criteria Updates

If you update criteria after scoring some candidates:

Existing scores retain the criteria version used at scoring time
New scores use the updated criteria
Each score is linked to its specific criteria version for audit purposes

See Criteria Management for how to update criteria.

Re-scoring Candidates

To re-score a candidate (e.g., after updating criteria), set rescore: true:

{
  "jobId": "job-123",
  "applicationId": "app-456",
  "candidate": {
    "resumeUrl": "https://..."
  },
  "rescore": true
}

This bypasses idempotency and creates a new scoring job using the current criteria.

Re-scoring counts as an additional billable score. Idempotent retries (same IDs without rescore: true) are not charged again.

See Idempotency for details.

Batch Scoring

For scoring multiple candidates at once, use POST /v1/score/batch:

{
  "jobId": "job-123",
  "candidates": [
    {
      "applicationId": "app-001",
      "candidate": { "resumeUrl": "https://..." }
    },
    {
      "applicationId": "app-002",
      "candidate": { "resumeUrl": "https://..." }
    }
  ]
}

Up to 100 candidates per batch
All candidates must be for the same job
Results delivered individually via webhook
Supports rescore: true at the batch level

See Score Batch for details.

Retrieving Scores

You can retrieve scores two ways:

Method	Endpoint	Use Case
By scoring job ID	`GET /v1/score/{scoringJobId}`	When you have Nova’s ID from the submission response
By application ID	`GET /v1/jobs/{jobId}/applications/{applicationId}/score`	When you only have your own application ID

See Get Score by Scoring Job ID or Get Score by Application ID for details.

Next Step

Set up your Webhook Endpoint to receive results.

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

jobId

string

required

Your job ID. Must have active criteria stored (via /v1/criteria/generate).

applicationId

string

required

Your application ID (echoed in webhook)

candidate

object

required

Show child attributes

candidate.resumeUrl

string<uri>

required

Pre-signed URL to the candidate's resume. Must be valid for at least 2 hours.

candidate.parsedResume

object

Structured resume data if available (improves accuracy)

candidate.applicationAnswers

object

object[]
object

language

string

default:English

Language for assessment output

rescore

boolean

default:false

When true, bypasses idempotency and creates a new scoring job even if this application was previously scored. Use after updating criteria to re-score existing candidates. Counts as an additional billable score.

Response

Scoring job accepted and queued

scoringJobId

string

required

Unique identifier for this scoring job

status

enum<string>

required

Initial status is always 'queued'

Available options:

queued

estimatedCompletionSeconds

integer

Estimated time until completion

Getting started

Core concepts

API endpoints

Integration guides

How It Works

Request

Prerequisites

Request Requirements

Resume URL

Optional: Parsed Resume

Optional: Application Answers

Idempotency

Response

Processing Time

What Happens Next

Criteria Updates

Re-scoring Candidates

Batch Scoring

Retrieving Scores

Next Step

Authorizations

Headers

Body

Response

Getting started

Core concepts

API endpoints

Integration guides

​How It Works

​Request

​Prerequisites

​Request Requirements

​Resume URL

​Optional: Parsed Resume

​Optional: Application Answers

​Idempotency

​Response

​Processing Time

​What Happens Next

​Criteria Updates

​Re-scoring Candidates

​Batch Scoring

​Retrieving Scores

​Next Step

Authorizations

Headers

Body

Response

How It Works

Request

Prerequisites

Request Requirements

Resume URL

Optional: Parsed Resume

Optional: Application Answers

Idempotency

Response

Processing Time

What Happens Next

Criteria Updates

Re-scoring Candidates

Batch Scoring

Retrieving Scores

Next Step