Submit and recover batches
Import applications while preserving per-item outcomes and avoiding duplicate work.
Use batches when you have several applications to submit. Each item keeps its own itemKey so your system can reconcile outcomes even when some fail. A batch is not an all-or-nothing transaction.
Submit a batch
Batch bodies contain items: [{ "itemKey": "row-1", "input": { ... } }]. Each key must be unique within the batch. The maximum is 20 items, 256 KiB, and one active batch of each kind per workspace.
- POST
/api/v1/upload-batcheswith upload inputs. Put a sharedjobDescriptionat the envelope level or set it per item. Supply an idempotency key. - Poll
/api/v1/upload-batches/{id}. Successful items contain report IDs and fresh upload URLs while the preparations remain available. PUT each resume to its URL. - POST report IDs as items to
/api/v1/analysis-batch-quotes. Each item returns a quote or a safe error reason. Credit costs are per item; quotes do not reserve credits. - POST successful items, including their quoted fingerprints, to
/api/v1/analysis-batcheswith a stable key. Poll the returned status URL.
Bulk invitations use /api/v1/interview-batch-quotes and /api/v1/interview-batches with the single-interview bodies. They require sendEmail: true and send invitation emails through the same durable delivery path. Use single invitations when your system delivers links.
202 accepts orchestration. Items can be queued, processing, waiting, admitted, succeeded, or failed. Capacity-limited items wait; unadmitted items have a one-hour deadline. Five analyses can be active per workspace across API, UI, and batches. Work budgets also limit bulk admission to 20 items per minute (10 for interviews).
Analysis batches complete when every admitted analysis finishes or fails. Invitation batches complete when invitations are accepted or rejected, independently of candidate completion. batch.completed contains the batch ID and outcome counts. Fetch its status for item details. Resume mismatch is a completed analysis requiring human review; inspect the report status separately.
Valid domain failures are per item. Unknown or foreign report/job IDs reject the envelope before scheduling. A revoked key stops unadmitted items; already admitted work continues. Retry failed items with new explicit item/batch identities and fresh quotes. Preserve successful resource IDs to avoid creating duplicate work or charges.
Minimal analysis batch
Upload each resume and quote it first. Use actual report IDs and quote fingerprints in place of these example values:
{
"items": [
{ "itemKey": "application-42", "input": {
"reportId": "report_example",
"quoteFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}}
]
}Send this to Create an analysis batch with an idempotency key. Store the returned batch ID before polling. A batch-level timeout is retried with the original key and body.
Interpret completion
| Kind | Successful item means | Next step |
|---|---|---|
| Upload | Preparation created | PUT file bytes, then obtain analysis quotes |
| Analysis | Admitted analysis reached its terminal outcome | Fetch the report; inspect mismatch and failure status |
| Interview | Invitation admitted | Follow each interview's preparation, candidate progress, and evaluation |
Recover only failed work
Persist itemKey, state, resource ID, attempt ID, and error code. Keep successful IDs even when another item fails. Correct the rejected input or wait for available allowance, then obtain fresh quotes for analysis/interview retries and create a new batch containing only those items.
Do not resubmit an entire completed batch under a fresh key to fix one failed row. For a lost response, retrieve or replay the original batch instead. Errors and retries explains capacity, stale quotes, and idempotency conflicts.