Withdraw a candidate | CONFIRM Docs

curl -X POST https://api.confirm.global/partner/v1/organizations/org_4Nv8sJqKfH/candidates/cand_5DkW9rTzPe/withdraw \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'

{
  "id": "cand_5DkW9rTzPe",
  "org_id": "org_4Nv8sJqKfH",
  "job_id": "job_2VbY6mQwXs",
  "external_ref": "cl_app_84321",
  "first_name": "Maria",
  "last_name": "Alvarez",
  "phone": "+18135550172",
  "email": "string",
  "source": "registry-platform",
  "status": "pending_contact",
  "stage": "applied",
  "consent": {
    "tcpa": true,
    "captured_at": "2024-01-15T09:30:00Z",
    "fcra_disclosure": true
  },
  "resume_url": "string",
  "metadata": {
    "county": "Hillsborough",
    "shift_preference": "weekends"
  },
  "withdrawn_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

Withdraws the candidate’s open application from your side (for example the applicant withdrew on your platform). Any in-flight screening attempts are cancelled, the screening status becomes withdrawn, and a candidate.withdrawn webhook is emitted. Returns 409 if the candidate has no open application to withdraw.

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

Request

This endpoint expects an object.

reasonstringOptional

Optional free-text reason recorded on the candidate timeline.

Response

The withdrawn 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

409

Conflict Error

429

Too Many Requests Error

Authentication

Path parameters

Headers

Request

Response

Errors