API concepts
Understand resources, quotes, retries, pagination, and result versions before integrating.
The API models a candidate application as a report with analysis and interview attempts. Keep each identity in a separate field in your system: a report ID is not an interview ID, and an external reference is not a credential.
Resource identities
| Value | Meaning | When it changes |
|---|---|---|
reportId | One prepared candidate-to-job report | A new preparation/application |
externalReference | Your source + application ID | Choose a new reference for a genuinely new application |
attemptId | One admitted resume-analysis run | A deliberate new run after an eligible failure |
interviewId | One logical interview attempt | A reinterview |
itemKey | Your row identifier within a batch | Chosen by your application for each batch |
Idempotency-Key | One logical write request | A genuinely new operation, not a network retry |
Worker retries keep the same analysis attempt. A reinterview preserves the prior public result on its prior interview ID. Do not use a candidate email as an application reference.
Why quote before submitting?
A quote returns the assigned version, applicable creditUnits and creditScale, and an opaque fingerprint. Divide units by scale for the displayed credit amount. Examples contain illustrative values; your workspace's response is authoritative.
The fingerprint lets submission detect a change to the configuration you reviewed. Copy it unchanged into quoteFingerprint and retain the same quoted inputs. Quotes do not start work, email candidates, or reserve capacity. If submission returns QUOTE_STALE, review a new quote and create a new submission key.
A successful quote does not guarantee admission. The workspace's available allowance and active-work limits are checked when work is accepted.
Accepted versus completed
A 202 means the request registered or admitted asynchronous work. Save the returned IDs and statusUrl. Poll with your API key or receive webhooks, then fetch the result.
A report can require human review rather than publish a full result. Interview lifecycle, preparation, evaluation, and email delivery are separate: the candidate can finish before evaluation is ready. A completed batch can contain failed items.
Retry one logical operation
Persist the request body and idempotency key before sending an important write. If the network times out, resend both unchanged. Switching to a new key can create new work; a timeout does not prove failure.
Keys are scoped to workspace and operation and survive API-key rotation. Changed input with an existing key returns a conflict. Receipts can outlive deleted resources, so deleting and retrying an old key is not a way to start again.
Pagination
List responses contain items and nextCursor. Follow the cursor without changing filters; null ends an ordinary resource list. Changing filters requires a new first page. Cursors are opaque, signed, and bound to workspace and filters.
The event feed differs: it always returns a cursor, including on empty pages. Save it only after processing the page durably. hasMore indicates whether more retained events are immediately available. See event recovery.
Three different versions
| Field | Meaning |
|---|---|
schemaVersion | Public payload format; currently request 1 for detailed results |
reportSystemVersion / interviewSystemVersion | Assigned product configuration captured for the work |
resultRevision | Particular published evaluation of that resource/attempt |
Only the assigned version is exposed; customers do not select from an internal version catalog. Existing work retains its captured version. Store result revisions so repeated notifications do not cause duplicate downstream processing.
Missing evidence
null means unavailable or not measured, not zero. An empty evidence list means no public entries were returned. Resume/skill scores use 0–10; interview readiness and requirement confidence/coverage use 0–100. Display evidence and limitations with scores; they are not probabilities of hiring success.