Set your outcome for an applicant at one location

Records your own decision about an applicant at one location:

`outcome`	Use it when	Resulting `status`
`withdrawn`	The applicant pulled out of this location.	`rejected`
`not_hired`	The office decided not to hire them for this location.	`rejected`
`hired`	The office hired them for this location.	`hired`

Only these final outcomes can be set. Screening and review steps are run by CONFIRM and can’t be set from outside.

One location at a time. Name the location with the location_ref query parameter. The applicant’s applications at other locations are not touched. There is no DELETE: to take an applicant off one location, set withdrawn (their choice) or not_hired (the office’s choice).

No messages to the applicant. CONFIRM sends the applicant nothing about an outcome you set; you made the decision and own that conversation.

You get your own change back as a webhook. When the outcome changes the applicant’s status at that location, CONFIRM fires candidate.status_changed (rejected or hired) to the applicant’s callback URL, like any other status change. Expect it and deduplicate it against the change you just made.

Idempotent. Setting the outcome the application already has returns 200 with changed: false and fires nothing. A different outcome replaces the earlier one. Switching between withdrawn and not_hired updates the recorded reason and returns changed: true, but the status stays rejected, so no new candidate.status_changed fires.

Do-not-contact is final. An applicant CONFIRM has marked do-not-contact can’t take an outcome: 409 outcome_conflict.

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

external_refstringRequired

Your applicant identifier (the external_ref you sent to POST /candidates).

Query parameters

location_refstringRequired>=1 character

The location the outcome applies to (its external_ref).

organization_refstringOptional

The registry the location belongs to. Only required when the same location ref exists in more than one of your registries.

Request

This endpoint expects an object.

outcomeenumRequired

Your decision for this applicant at this location.

Allowed values:

reasonstringOptional<=1000 characters

Optional free text, kept with the change in CONFIRM’s history for this application. For withdrawn and not_hired it is recorded as the reason the applicant is no longer progressing.

Response headers

X-Request-IdstringOptional

The ID of this request. On an error it equals request_id in the body. If you sent an X-Request-Id, it is your value, returned unchanged. Log it, and quote it when contacting CONFIRM support.

Response

The outcome is recorded (or was already in place: changed is false).

candidate_idstringformat: "uuid"

application_idstringformat: "uuid"

The application at location_ref.

external_refstring

location_refstring

outcomeenum

The outcome you sent, echoed back.

Allowed values:

changedboolean

False when the application already had this outcome and nothing changed.

statusenum or nullOptional

The applicant's coarse status at this location after the change.

Allowed values:

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

409

Conflict Error

429

Too Many Requests Error