Score Application

@nova-sdk/api

import { Nova } from "@nova-sdk/api";

const nova = new Nova({
  apiKey: "sk_test_...",
  tenantId: "acme-corp",
});

const result = await nova.jobs.applications.scoringJobs.submit({
  jobId: "job_abc123",
  applicationId: "app_xyz789",
  body: {
    resume: { type: "url", url: "https://example.com/resumes/application-123.pdf" },
    jobDescription: "We are looking for a senior engineer...",
  },
});

curl -X POST "https://embed.nova.dweet.com/v1/jobs/job_abc123/applications/app_xyz789/scoring-jobs" \
  -H "Authorization: Bearer sk_test_..." \
  -H "X-Tenant-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
  "resume": {
    "type": "url",
    "url": "https://example.com/resumes/application-123.pdf"
  },
  "jobDescription": "We are looking for a senior engineer..."
}'

{
  "scoringJob": {
    "id": "<string>",
    "criteriaVersionId": "<string>",
    "jobId": "<string>",
    "applicationId": "<string>",
    "status": "pending",
    "isRescore": true,
    "score": 123,
    "assessment": {
      "verdict": "<string>",
      "strengths": [
        "<string>"
      ],
      "concerns": [
        "<string>"
      ],
      "interviewFocus": [
        "<string>"
      ]
    },
    "errorCode": "UNAUTHORIZED",
    "errorMessage": "<string>",
    "queuedAt": "2023-11-07T05:31:56Z",
    "startedAt": "2023-11-07T05:31:56Z",
    "completedAt": "2023-11-07T05:31:56Z",
    "failedAt": "2023-11-07T05:31:56Z"
  }
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

POST

jobs

{jobId}

applications

{applicationId}

scoring-jobs

@nova-sdk/api

import { Nova } from "@nova-sdk/api";

const nova = new Nova({
  apiKey: "sk_test_...",
  tenantId: "acme-corp",
});

const result = await nova.jobs.applications.scoringJobs.submit({
  jobId: "job_abc123",
  applicationId: "app_xyz789",
  body: {
    resume: { type: "url", url: "https://example.com/resumes/application-123.pdf" },
    jobDescription: "We are looking for a senior engineer...",
  },
});

curl -X POST "https://embed.nova.dweet.com/v1/jobs/job_abc123/applications/app_xyz789/scoring-jobs" \
  -H "Authorization: Bearer sk_test_..." \
  -H "X-Tenant-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
  "resume": {
    "type": "url",
    "url": "https://example.com/resumes/application-123.pdf"
  },
  "jobDescription": "We are looking for a senior engineer..."
}'

{
  "scoringJob": {
    "id": "<string>",
    "criteriaVersionId": "<string>",
    "jobId": "<string>",
    "applicationId": "<string>",
    "status": "pending",
    "isRescore": true,
    "score": 123,
    "assessment": {
      "verdict": "<string>",
      "strengths": [
        "<string>"
      ],
      "concerns": [
        "<string>"
      ],
      "interviewFocus": [
        "<string>"
      ]
    },
    "errorCode": "UNAUTHORIZED",
    "errorMessage": "<string>",
    "queuedAt": "2023-11-07T05:31:56Z",
    "startedAt": "2023-11-07T05:31:56Z",
    "completedAt": "2023-11-07T05:31:56Z",
    "failedAt": "2023-11-07T05:31:56Z"
  }
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

Submit an application for scoring. Asynchronous. Nova loads the job’s active criteria automatically.

Request

Field	Required	Description
`resume`	Yes	The application resume
`resume.type`	Yes	`"url"` for file URL, `"text"` for inline text
`resume.url`	Conditional	HTTPS URL to resume file (PDF, DOC, DOCX)
`resume.content`	Conditional	Inline plain text or markdown (min 50 chars, max 100KB)
`jobDescription`	Yes	Job posting description for AI scoring context
`roleKnowledge`	No	Free-text: hiring team priorities, scoring preferences. Max 15,000 chars
`applicationData.applicationAnswers`	No	Structured Q&A pairs from screening questions
`applicationData.context`	No	Free-text: cover letters, hiring notes. Max 15,000 chars
`rescore.enabled`	Yes (if `rescore` provided)	When `true`, create a new scoring job
`rescore.criteriaVersionId`	No	Pin re-scoring to a specific criteria version

See Supported Formats for resume format and URL requirements.

jobDescription is passed per-request. Resume files are retained for up to 30 days. Application scoring inputs such as jobDescription, roleKnowledge, applicationData.applicationAnswers, and applicationData.context are retained for 90 days. See Data Retention.

Response

Returns 202 Accepted with a scoring job. If Nova cannot fetch or validate the resume during intake, the request returns a 4xx error and no scoring job is created. Malformed or truncated PDF resumes return 422 RESUME_CORRUPTED; submit a corrected file before retrying.

{
  "scoringJob": {
    "id": "cmlz26dl3001bwp61r8sjf2ka",
    "criteriaVersionId": "cmlz26ck2000awp61q9qcjcne",
    "jobId": "job-123",
    "applicationId": "app-456",
    "status": "pending",
    "isRescore": false,
    "score": null,
    "assessment": null,
    "errorCode": null,
    "errorMessage": null,
    "queuedAt": "2025-12-14T10:30:45Z",
    "startedAt": null,
    "completedAt": null,
    "failedAt": null
  }
}

Status Values

Status	Description
`pending`	Queued or currently scoring
`completed`	Finished successfully
`failed`	Finished with an error

Result Delivery

Results come via webhook. Use polling as a fallback.

Webhooks
Get Scoring Job (polling)

Example

import { Nova } from '@nova-sdk/api';

const nova = new Nova({
  apiKey: process.env.NOVA_API_KEY!,
  tenantId: 'acme-corp',
});

const { scoringJob } = await nova.jobs.applications.scoringJobs.submit({
  jobId: 'job-123',
  applicationId: 'app-456',
  body: {
    resume: { type: 'url', url: 'https://storage.example.com/resumes/abc123.pdf' },
    jobDescription: 'We are looking for a Senior Software Engineer with 5+ years experience...',
    roleKnowledge: 'Team values applicants who have built systems from scratch.',
  },
});

curl -X POST 'https://embed.nova.dweet.com/v1/jobs/job-123/applications/app-456/scoring-jobs' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'X-Tenant-Id: acme-corp' \
  -H 'Content-Type: application/json' \
  -d '{
    "resume": { "type": "url", "url": "https://storage.example.com/resumes/abc123.pdf" },
    "jobDescription": "We are looking for a Senior Software Engineer with 5+ years experience...",
    "roleKnowledge": "Team values applicants who have built systems from scratch."
  }'

Idempotency

This endpoint uses built-in scoring idempotency. Re-submitting the same jobId and applicationId returns the existing scoring job. Idempotency-Key is ignored here. See Idempotency for retry, duplicate submission, and re-scoring behavior.

The HTTP replay header Idempotent-Replayed: true never appears on this endpoint because it stays outside the generic Idempotency-Key middleware.

Batch Scoring

Score multiple applications at once with POST /v1/jobs/{jobId}/scoring-batches.

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

applicationId

string

required

Your application identifier (external ID).

Body

application/json

resume

object

required

Option 1
Option 2

Show child attributes

jobDescription

string

required

The job posting description. Provides context for AI scoring alongside criteria

Required string length: 1 - 50000

applicationData

object

Show child attributes

jobTitle

string

Minimum string length: 1

companyName

string

Minimum string length: 1

roleKnowledge

string

Free-text context about the role: hiring team priorities, scoring preferences, or any additional guidance that helps the AI evaluate applications. Max 15,000 chars

Required string length: 1 - 15000

rescore

object

Re-scoring configuration. When provided with enabled: true, creates a new scoring job

Show child attributes

Response

Accepted

scoringJob

object

required

Show child attributes

Getting started

Core concepts

API endpoints

Integration guides

SDKs

Legal

Request

Response

Status Values

Result Delivery

Example

Idempotency

Batch Scoring

Authorizations

Headers

Path Parameters

Body

Response

​Request

​Response

​Status Values

​Result Delivery

​Example

​Idempotency

​Batch Scoring

Authorizations

Headers

Path Parameters

Body

Response

Request

Response

Status Values

Result Delivery

Example

Idempotency

Batch Scoring