> ## Documentation Index
> Fetch the complete documentation index at: https://nova.dweet.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Score Application
> Submit an application for asynchronous AI scoring against job criteria
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](/embed-api/guides/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](/embed-api/concepts/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.
```json theme={null}
{
"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](/embed-api/concepts/webhooks)
* [Get Scoring Job](/embed-api/endpoints/results-by-scoring-job) (polling)
## Example
```typescript TypeScript SDK theme={null}
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.',
},
});
```
```bash cURL theme={null}
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](/embed-api/concepts/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`.
## OpenAPI
````yaml POST /v1/jobs/{jobId}/applications/{applicationId}/scoring-jobs
openapi: 3.1.0
info:
title: Nova Embed API
description: >-
The Nova Embed API enables ATS platforms to generate job-scoped screening
criteria and score applications asynchronously against those criteria.
version: 1.0.0
contact:
name: Nova Support
email: nova@dweet.com
servers:
- url: https://embed.nova.dweet.com
description: >-
Environment is determined by API key prefix: sk_test_* for sandbox,
sk_live_* for production.
security:
- bearerAuth: []
tags:
- name: Analytics
description: View scoring performance, webhook health, and error breakdowns.
- name: Criteria
description: Generate and manage job-scoped screening criteria.
- name: Scoring
description: Submit applications for scoring and fetch scoring job results.
- name: Deletion
description: Request application or tenant deletion and poll for completion.
- name: Criteria Library
description: Manage tenant-scoped reusable criteria templates.
- name: Rate Limits
description: Check your current rate limit status.
- name: Webhooks
description: >-
Events sent to your registered webhook endpoints. Verify signatures with
HMAC-SHA256 using your webhook secret.
paths:
/v1/jobs/{jobId}/applications/{applicationId}/scoring-jobs:
post:
tags:
- Scoring
summary: Submit scoring job
description: >-
Scoring submissions are idempotent by default based on your tenant,
jobId, applicationId, and rescore identity. This operation does not use
the generic Idempotency-Key replay layer.
operationId: submitScoringJob
parameters:
- $ref: '#/components/parameters/TenantId'
- $ref: '#/components/parameters/JobId'
- $ref: '#/components/parameters/ApplicationId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitScoreRequest'
responses:
'202':
description: Accepted
headers:
X-RateLimit-Bucket:
$ref: '#/components/headers/X-RateLimit-Bucket'
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitScoreResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
'401':
$ref: '#/components/responses/ErrorResponse'
'404':
$ref: '#/components/responses/ErrorResponse'
'422':
$ref: '#/components/responses/ErrorResponse'
'429':
$ref: '#/components/responses/RateLimitedResponse'
'500':
$ref: '#/components/responses/ErrorResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
x-codeSamples:
- lang: typescript
label: '@nova-sdk/api'
source: |-
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...",
},
});
- lang: bash
label: cURL
source: >-
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..."
}'
components:
parameters:
TenantId:
name: X-Tenant-Id
in: header
required: true
description: Your customer identifier. Tenants are auto-provisioned on first request.
schema:
type: string
example: acme-corp
JobId:
name: jobId
in: path
required: true
description: Your job identifier (external ID).
schema:
type: string
ApplicationId:
name: applicationId
in: path
required: true
description: Your application identifier (external ID).
schema:
type: string
schemas:
SubmitScoreRequest:
type: object
properties:
resume:
$ref: '#/components/schemas/ResumeInput'
applicationData:
$ref: '#/components/schemas/ApplicationData'
jobDescription:
type: string
minLength: 1
maxLength: 50000
description: >-
The job posting description. Provides context for AI scoring
alongside criteria
jobTitle:
type: string
minLength: 1
companyName:
type: string
minLength: 1
roleKnowledge:
description: >-
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
type: string
minLength: 1
maxLength: 15000
rescore:
description: >-
Re-scoring configuration. When provided with enabled: true, creates
a new scoring job
type: object
properties:
enabled:
type: boolean
description: When true, create a new scoring job for this application
criteriaVersionId:
description: >-
Pin scoring to a specific criteria version. Only used when
enabled is true
type: string
required:
- enabled
additionalProperties: false
required:
- resume
- jobDescription
additionalProperties: false
SubmitScoreResponse:
type: object
required:
- scoringJob
properties:
scoringJob:
$ref: '#/components/schemas/ScoringJob'
ResumeInput:
oneOf:
- type: object
required:
- type
- url
additionalProperties: false
properties:
type:
type: string
const: url
url:
type: string
format: uri
description: >-
HTTPS URL to resume file (PDF, DOC, DOCX). Must be publicly
accessible.
- type: object
required:
- type
- content
additionalProperties: false
properties:
type:
type: string
const: text
content:
type: string
minLength: 50
description: Inline resume text (plain text or markdown, max 100KB)
discriminator:
propertyName: type
ApplicationData:
type: object
properties:
applicationAnswers:
type: array
items:
type: object
properties:
question:
type: string
minLength: 1
answer:
type: string
required:
- question
- answer
additionalProperties: false
context:
type: string
minLength: 1
maxLength: 15000
additionalProperties: false
ScoringJob:
type: object
required:
- id
- criteriaVersionId
- jobId
- applicationId
- status
- isRescore
- score
- assessment
- errorCode
- errorMessage
- queuedAt
- startedAt
- completedAt
- failedAt
properties:
id:
type: string
criteriaVersionId:
type: string
description: >-
The criteria version snapshot used for scoring. Fetch the snapshot
via GET /v1/jobs/{jobId}/criteria/versions/{criteriaVersionId}.
jobId:
type: string
applicationId:
type: string
status:
$ref: '#/components/schemas/ScoringJobStatus'
isRescore:
type: boolean
score:
type:
- number
- 'null'
assessment:
oneOf:
- $ref: '#/components/schemas/Assessment'
- type: 'null'
errorCode:
oneOf:
- $ref: '#/components/schemas/ErrorCode'
- type: 'null'
errorMessage:
type:
- string
- 'null'
queuedAt:
type: string
format: date-time
startedAt:
type:
- string
- 'null'
format: date-time
completedAt:
type:
- string
- 'null'
format: date-time
failedAt:
type:
- string
- 'null'
format: date-time
HttpError:
type: object
required:
- type
- code
- status
- message
- retryable
- traceId
properties:
type:
type: string
description: URI reference that identifies the error type
code:
$ref: '#/components/schemas/ErrorCode'
status:
type: integer
description: HTTP status code
message:
type: string
description: Error message
retryable:
type: boolean
description: When true, retrying the request may succeed
traceId:
type: string
description: Trace ID for debugging
details:
type:
- array
- 'null'
description: Field-level validation details
items:
type: object
required:
- field
- code
- message
properties:
field:
type: string
code:
type: string
message:
type: string
ScoringJobStatus:
type: string
enum:
- pending
- completed
- failed
Assessment:
type: object
required:
- verdict
- strengths
- concerns
- interviewFocus
properties:
verdict:
type: string
strengths:
type: array
items:
type: string
concerns:
type: array
items:
type: string
interviewFocus:
type: array
items:
type: string
ErrorCode:
type: string
description: >-
Machine-readable error code. Generated from the canonical error
registry.
enum:
- UNAUTHORIZED
- FORBIDDEN
- VALIDATION_ERROR
- ANSWER_MISMATCH
- CRITERIA_INVALID
- CRITERIA_REVISION_CONFLICT
- NOT_FOUND
- TENANT_NOT_FOUND
- JOB_NOT_FOUND
- APPLICATION_NOT_FOUND
- QUESTION_SET_NOT_FOUND
- CRITERIA_NOT_FOUND
- CRITERION_NOT_FOUND
- CRITERIA_VERSION_NOT_FOUND
- SCORING_JOB_NOT_FOUND
- BATCH_NOT_FOUND
- LIBRARY_CRITERION_NOT_FOUND
- RATE_LIMITED
- MONTHLY_TRIAL_QUOTA_EXCEEDED
- IDEMPOTENCY_KEY_ALREADY_USED
- IDEMPOTENCY_REQUEST_IN_PROGRESS
- RESUME_FETCH_FAILED
- RESUME_CONVERSION_FAILED
- RESUME_ENCRYPTED
- RESUME_CORRUPTED
- RESUME_PARSE_FAILED
- RESUME_TOO_LARGE
- RESUME_EMPTY
- RESUME_URL_BLOCKED
- AI_PROCESSING_FAILED
- AI_GENERATION_FAILED
- AI_SCORING_FAILED
- MISSING_JOB_DESCRIPTION
- TIMEOUT
- MAX_RETRIES_EXCEEDED
- TASK_STUCK
- DELETION_REQUEST_NOT_FOUND
- DELETION_REQUEST_FAILED
- INTERNAL_ERROR
- SERVICE_UNAVAILABLE
- UNKNOWN
headers:
X-RateLimit-Bucket:
description: Which rate limit bucket the request was classified into
schema:
type: string
enum:
- criteria_ai
- criteria_current_reads
- scoring_intake_batch
- scoring_intake_single
- read_and_ops
- rate_limit_status
- analytics
X-RateLimit-Limit:
description: Maximum requests per second for this bucket
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current 1-second window
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp when the current window resets
schema:
type: integer
Retry-After:
description: >-
Seconds to wait before retrying a short-window RATE_LIMITED or
service-unavailable response whose body has retryable: true.
schema:
type: integer
X-RateLimit-Degraded:
description: >-
Present and set to "true" when rate limiting is operating in degraded
mode (Redis unavailable). Values in other rate limit headers are
best-effort estimates.
schema:
type: string
enum:
- 'true'
responses:
ErrorResponse:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/HttpError'
RateLimitedResponse:
description: >-
Too many requests. Short-window RATE_LIMITED responses include retry
timing and rate limit headers. Monthly trial quota responses use
MONTHLY_TRIAL_QUOTA_EXCEEDED with retryable: false.
headers:
Retry-After:
$ref: '#/components/headers/Retry-After'
X-RateLimit-Bucket:
$ref: '#/components/headers/X-RateLimit-Bucket'
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-RateLimit-Degraded:
$ref: '#/components/headers/X-RateLimit-Degraded'
content:
application/json:
schema:
$ref: '#/components/schemas/HttpError'
ServiceUnavailableResponse:
description: Service temporarily unavailable
headers:
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/HttpError'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key
description: 'Use Authorization: Bearer sk_test_* or Authorization: Bearer sk_live_*.'
````