Score Batch

Submit multiple applications for scoring in a single request

POST /v1/jobs/{jobId}/scoring-batches

@nova-sdk/api

TypeScript

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

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

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

202

{
  "batch": {
    "id": "<string>",
    "jobId": "<string>",
    "totalJobs": 123,
    "completedJobs": 123,
    "failedJobs": 123,
    "createdAt": "2023-11-07T05:31:56Z",
    "completedAt": "2023-11-07T05:31:56Z"
  },
  "scoringJobIds": [
    "<string>"
  ],
  "acceptedApplications": [
    {
      "applicationId": "<string>",
      "scoringJobId": "<string>"
    }
  ],
  "rejectedApplications": [
    {
      "applicationId": "<string>",
      "error": {
        "message": "<string>",
        "reason": "<string>"
      }
    }
  ]
}

Submit multiple applications for scoring in a single request. Results are delivered individually via webhook.

If some resume inputs are invalid, Nova accepts the valid applications and returns the invalid ones in rejectedApplications. Rejected applications are pre-queue intake rejections: no scoring job is created and no score.failed webhook is emitted for them.

Request

TypeScript SDK

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

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

const { batch, scoringJobIds, acceptedApplications, rejectedApplications } =
  await nova.jobs.scoringBatches.submit({
  jobId: 'job-123',
  body: {
    jobDescription: 'We are looking for a Senior Backend Engineer with 5+ years of experience in Node.js and TypeScript...',
    roleKnowledge: "Team values applicants who've built systems from scratch. Strong preference for distributed systems experience over frontend-heavy backgrounds.",
    applications: [
      {
        applicationId: 'app-001',
        resume: { type: 'url', url: 'https://storage.example.com/resumes/001.pdf' },
      },
      {
        applicationId: 'app-002',
        resume: { type: 'text', content: '# Jane Smith\n\nSenior Backend Engineer with 7 years of experience...' },
        applicationData: {
          applicationAnswers: [
            { question: 'Are you eligible to work in the UK?', answer: 'Yes' },
          ],
          context: 'Internal recruiter note: Strong referral from engineering lead. Applicant expressed interest in platform team specifically.',
        },
      },
    ],
  },
});

console.log(acceptedApplications);
console.log(rejectedApplications);

Include jobDescription at the batch level. It applies to all applications in the batch. See Data Retention for storage details.

Idempotency

Re-submitting the same jobId and set of applicationId values returns the existing batch.

This endpoint uses built-in batch scoring idempotency. Idempotency-Key is ignored here. To recover from a timeout or network uncertainty, re-submit the same batch for the same jobId. To create fresh scoring work for an application, use the single scoring endpoint with rescore.

If a previous submission rejected an application and you later fix that resume, re-submitting the exact same batch shape returns the original rejection. Submit the corrected application with a distinct batch shape or use the single scoring endpoint.

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

See Idempotency for the full retry model.

Limits

• 1 to 25 applications per request

Response

The API returns 202 Accepted.

{
  "batch": {
    "id": "cmlz26em4002cwp61t7ukh3lb",
    "jobId": "job-123",
    "status": "pending",
    "totalJobs": 2,
    "completedJobs": 0,
    "failedJobs": 0,
    "createdAt": "2025-12-14T10:30:45Z",
    "completedAt": null
  },
  "scoringJobIds": ["cmlz26dl3001bwp61r8sjf2ka", "cmlz26dl3001bwp61r8sjf2kb"],
  "acceptedApplications": [
    {
      "applicationId": "app-001",
      "scoringJobId": "cmlz26dl3001bwp61r8sjf2ka"
    },
    {
      "applicationId": "app-002",
      "scoringJobId": "cmlz26dl3001bwp61r8sjf2kb"
    }
  ],
  "rejectedApplications": []
}

totalJobs, completedJobs, and failedJobs count accepted applications only. Rejected applications are returned in deterministic applicationId order.

If every application is rejected before queueing, the API returns 422 VALIDATION_ERROR with per-application details and does not create a batch.

{
  "code": "VALIDATION_ERROR",
  "status": 422,
  "message": "No applications could be accepted for scoring",
  "retryable": false,
  "details": [
    {
      "field": "applications[app-bad].resume",
      "code": "RESUME_CORRUPTED",
      "message": "Resume file appears to be corrupted"
    }
  ],
  "traceId": "trace_..."
}

Next step

Use Get Batch Status to poll batch progress if you need it.

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

Body

application/json

applications · object[] · required

Required array length: 1 - 25 elements

Show child attributes

jobDescription · string · required

Required string length: 1 - 50000

jobTitle · string

Minimum string length: 1

companyName · string

Minimum string length: 1

roleKnowledge · string

Required string length: 1 - 15000

Response

202

application/json

Accepted

batch · object · required

Show child attributes

scoringJobIds · string[] · required

acceptedApplications · object[] · required

Show child attributes

rejectedApplications · object[] · required

Show child attributes