Update or close a location
Updates a location’s title, description, address, or pay, or closes it
to new applicants with status: closed. Omitted fields are unchanged;
closing a location leaves existing candidates and their in-flight
screenings untouched.
Pay. pay replaces the stored pay rate as a whole: a key you leave
out is cleared, not kept. pay: null clears the pay rate; leaving pay
out leaves it alone. A location with no pay after the update answers
with the no-pay warning in warnings.
Closing. While a location is closed, POST /candidates to it returns
409 location_closed for new applicants. An applicant you sent before
closing still returns 200 with deduped: true, so replaying a retry
queue is safe. Set status: active to accept applicants again. Closing
and reopening don’t touch the address or coordinates, so distance
screening resumes as it was.
Address. address replaces the stored address as a whole: a field
you leave out is cleared, not kept. Send the full address every time.
The location is re-geocoded, and the previous coordinates are cleared
first so a stale fix can never outlive the address it came from. An
address without a street still geocodes, to the centre of the city or
ZIP, and the response carries a warning saying so.
geocoded always reflects the location’s coordinates after the
update, including on updates that don’t change the address.
Same ref in several registries. Location refs only need to be unique
within a registry. If you use the same ref in more than one, pass
organization_ref to say which; without it the request returns
409 ambiguous_location_ref.
Authentication
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
Your location identifier (external_ref).
Query parameters
Request
Replaces the title, stored exactly as you send it. No “Caregiver — ” prefix is added; to keep that style, send the whole title, e.g. "Caregiver — Denver North".
Set closed to stop accepting new applicants at this location (POST /candidates returns 409 location_closed), and active to reopen it.
Replaces the location’s pay rate as a whole (keys left out are cleared). null clears the pay rate; omit the field to leave it unchanged.
Response headers
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
Your location identifier, echoed back. Pass it as location_ref when ingesting applicants.
True when the location has coordinates. False means distance screening is inactive for this location — check warnings. An address without a street geocodes to the centre of the city or ZIP; warnings says so when that happens.
The stored single-line address.
False when the location already existed and this call was a no-op.
The location’s pay rate, or null when it has none. With null, warnings includes “No pay rate set — the pay question will be skipped on screening calls for this location.”