Retrieve a candidate

GET

https://api.confirm.global/partner/v1/organizations/:org_id/candidates/:cand_id

GET

/partner/v1/organizations/:org_id/candidates/:cand_id

$ curl https://api.confirm.global/partner/v1/organizations/org_4Nv8sJqKfH/candidates/cand_5DkW9rTzPe \
>      -H "Authorization: Bearer <token>"

1 {
2   "id": "cand_5DkW9rTzPe",
3   "org_id": "org_4Nv8sJqKfH",
4   "job_id": "job_2VbY6mQwXs",
5   "external_ref": "cl_app_84321",
6   "first_name": "Maria",
7   "last_name": "Alvarez",
8   "phone": "+18135550172",
9   "email": "string",
10   "source": "registry-platform",
11   "status": "pending_contact",
12   "stage": "applied",
13   "consent": {
14     "tcpa": true,
15     "captured_at": "2024-01-15T09:30:00Z",
16     "fcra_disclosure": true
17   },
18   "resume_url": "string",
19   "metadata": {
20     "county": "Hillsborough",
21     "shift_preference": "weekends"
22   },
23   "withdrawn_at": "2024-01-15T09:30:00Z",
24   "created_at": "2024-01-15T09:30:00Z",
25   "updated_at": "2024-01-15T09:30:00Z"
26 }

Retrieves a single candidate, including current partner status and v4 stage.

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.

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

Response

The candidate.

idstringOptional

Candidate ID (cand_...).

org_idstringOptional

job_idstringOptional

external_refstring or nullOptional

Your platform’s identifier for this applicant; echoed on every related API response and webhook.

first_namestringOptional

last_namestringOptional

phonestringOptional

E.164.

emailstring or nullOptionalformat: "email"

sourcestring or nullOptional

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.

resume_urlstring or nullOptionalformat: "uri"

metadatamap from strings to stringsOptional

Flat string-to-string map of your own data, up to 20 keys. Stored verbatim and echoed back on the candidate and in webhook payloads.

withdrawn_atdatetime or nullOptional

Set when the candidate was withdrawn via the withdraw endpoint.

created_atdatetimeOptional

updated_atdatetimeOptional

Errors

401

Unauthorized Error

404

Not Found Error

429

Too Many Requests Error