Add or move an applicant's location

Puts an applicant you already sent at another location in the same registry, or moves them there from a location they are at.

Add. Send location_ref alone. The applicant gets a new application at that location; their other applications are unchanged. You receive candidate.location_added.

Move. Also send move_from_location_ref. The new application is created as for an add, and the application at the old location is closed. A move is not a rejection: you receive one candidate.location_changed and no candidate.status_changed → rejected for the location they left. The applicant gets no message about the closed application.

Idempotent. 201 when a new application was created; 200 with created: false when the applicant already had one at that location, in which case nothing about that application changes. Replaying a move is safe: if the old location’s application is still open, the replay closes it.

Screening is reused, and only the gaps are asked. The new application copies the applicant’s completed screening when it covers the new location. screening in the response says which case applied:

`screening`	Meaning
`reused`	The applicant passed a screening in this registry that asked every question the new location asks. The new application starts at the step after screening, as if they had passed there, and that step’s usual messages are sent (for example, an interview booking link). No call is placed.
`pending`	The applicant has a completed screening in this registry, but it failed or was partial, or the new location asks questions it did not cover. The new application starts at screening, and a follow-up call covers what is missing (below). A failed screening elsewhere does not by itself reject the applicant here: knockouts are per location, and an earlier failed answer counts here only when this location asks the same question in the same words with the same knockout rule.
`none`	No screening to reuse: the applicant has no completed screening in this registry yet, or the application already existed (`created: false`). A new application starts at the beginning of the pipeline, and is screened as described below.

Follow-up calls. For a new application with screening pending or none, CONFIRM works out what is still unanswered:

If the applicant’s screening call has not been placed yet, the new location joins it.
If a call for another of their locations is in progress, the new location waits for it to finish, then continues below.
Otherwise a short follow-up call asks only the questions the applicant has not already answered. Earlier answers carry over only when the question is asked exactly the same way: a question that names a different address, for example, is asked again.
If nothing is left to ask, no call is placed: the outcome at the new location is decided from the earlier answers.

There is no second heads-up SMS. The applicant must have given contact consent and have a valid phone, as for any call. The result arrives as screening.completed and candidate.status_changed for the new location. screening in the response does not change with any of this. See follow-up calls.

Callback URL. The new application keeps the webhook_url the applicant was posted with (on a move, the old location’s), so its events reach the same place.

Paused locations are fine; closed ones are not. A target location closed with PATCH /locations/{ref} returns 409 location_closed, unless the applicant already has an application there (200).

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

Request

This endpoint expects an object.

location_refstringRequired>=1 character

The location to add the applicant to (its external_ref).

organization_refstringOptional>=1 character

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

move_from_location_refstringOptional>=1 character

Set to move instead of add: the location the applicant is leaving. Must be in the same registry as location_ref, the applicant must have an application there, and it must differ from location_ref.

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

Application created at the location. If the applicant already had one there you get 200 with created: false and that application.

candidate_idstringformat: "uuid"

application_idstringformat: "uuid"

The application at location_ref.

external_refstring

Your applicant identifier, echoed back.

location_refstring

The location, echoed back.

createdboolean

False when the applicant already had an application at this location.

screeningenum

How much of an existing screening the application reuses, at the moment it was created. See the table in the endpoint description. For pending and none, a follow-up call (or the applicant’s not-yet-placed screening call) covers the rest; this value does not change when it does.

Allowed values:

statusenum or nullOptional

The applicant's coarse status at this location.

Allowed values:

moved_fromobject or nullOptional

On a move, the location the applicant left and its now-closed application. null on an add.

portal_urlstring or nullOptionalformat: "uri"

Complete deep link to the applicant in the registry's portal.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

409

Conflict Error

429

Too Many Requests Error