Partner APIScreenings

Trigger a screening

Screenings are auto-triggered on candidate ingestion by default; use this endpoint to (re)trigger one manually — for example after contact attempts were exhausted and you have a corrected phone number. Returns 409 if a screening is already in progress for the candidate.

Authentication

AuthorizationBearer
Partner API key sent as `Authorization: Bearer cfk_...`. Keys are partner-level — one key reaches every registry linked to your partner account and nothing else. CONFIRM issues and revokes them; a key is shown exactly once at creation because only its hash is stored, and revocation takes effect on the next request. Develop against the sandbox base URL with a sandbox key, where telephony is restricted to an allowlist you provide.

Path parameters

org_idstringRequired

Organization ID (org_...).

cand_idstringRequired

Candidate ID (cand_...).

Headers

Idempotency-KeystringOptional<=255 characters

Unique key (e.g. a UUID) making this POST safe to retry. Replays within 24 hours return the original response without repeating side effects.

Response

Screening created and contact attempts queued.
idstringOptional

Screening ID (scr_...).

candidate_idstringOptional
external_refstring or nullOptional

The candidate’s external_ref, echoed for correlation.

job_idstringOptional
statusenumOptional

Simplified partner-facing screening status. Flow: pending_contact → contacting → terminal (completed, no_answer_exhausted, declined_recording, opted_out, withdrawn). When completed, see outcome for passed vs failed_knockout. The candidate’s full v4 stage slug rides along as stage.

stageenumOptional

Candidate lifecycle stage slug (v4). Rides along on screenings as stage for partners who want full lifecycle granularity; most integrations only need the simplified partner screening status.

attempt_countintegerOptional

Outbound contact attempts made so far (voicemails and no-answers included).

next_attempt_atdatetime or nullOptional
When the next automatic contact attempt is scheduled, if any.
started_atdatetime or nullOptional
When the candidate first connected to the AI screening call.
completed_atdatetime or nullOptional
outcomeenumOptional

Set only when the screening status is completed.

resultobjectOptional

Structured result, present once the screening status is completed. Signals are item-level only — the Partner API intentionally exposes no composite or overall score.

Errors

401
Unauthorized Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error