Skip to navigation
Partner APILocations

Create a location

Creates a screening-ready job for one of a registry’s locations. Call it when a location is added on your side.

Send a real street address. CONFIRM’s distance screening measures a candidate’s commute against it, so a location without one is created successfully but screens nobody on distance — the response says so in warnings.

You do not have to supply the job. Omit title and description and CONFIRM scaffolds its standard caregiver role for you — title, responsibilities, requirements and benefits — so your location-created job can post the address and nothing else. Supply them only when the location hires for something other than the default role.

Titles. Without a title, the job is titled “Caregiver — ” followed by the location’s name — or, when there is no name, its city, then the registry’s name. A title you send is stored exactly as you send it, here or on PATCH /locations/{ref}; nothing is added to it. So you never need to send the “Caregiver — ” prefix yourself. If you rename a location with PATCH and want to keep that style, send the whole title you want, e.g. "Caregiver — Denver North".

Send the pay rate. The screening call tells applicants what the location pays. A location without pay is created, but the response carries the warning “No pay rate set — the pay question will be skipped on screening calls for this location.” See pay below for the rules.

Idempotent on external_ref within the registry. Posting a ref that already exists returns 200 with the existing location and created: false, and changes nothing: a new name, title, address or pay in the body is ignored, and the response reports the pay the location already has. Use PATCH /locations/{ref} to change a location.

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.

Request

This endpoint expects an object.
external_refstringRequired

Your location identifier. Referenced later as location_ref when ingesting applicants.

organization_refstringRequired

The registry this location belongs to (the external_ref you provisioned it with).

namestringOptional

The location’s own name. Used to title the scaffolded job (“Caregiver — Clearwater”) when you don’t supply title. Without a name, the title uses the city, then the registry name.

titlestringOptional>=1 character

The job title for this location, stored exactly as you send it. Optional — omit it and the default caregiver role is used, titled “Caregiver — {name}”.

descriptionstringOptional

Role description. Used in candidate-facing copy and screening context. Optional — omit it and the default caregiver description is used.

employment_typestringOptional

Defaults to full-time when omitted.

addressobjectOptional
A real street address. Distance screening measures a candidate's commute against it, so the more complete it is, the better location fit works.
payobjectOptional

The location’s pay rate, as you send it. Every key is optional, but:

  • include at least one of min, max or text;
  • period is required when min or max is given;
  • min may not be greater than max.

Breaking a rule is a 400 invalid_request. The screening call uses the pay rate to answer the pay question; a location without one skips it.

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

Location created, with its job scaffolded. Posting an external_ref that already exists returns 200 with the existing location and created: false.

location_idstringformat: "uuid"
CONFIRM's identifier for the location's job.
external_refstring

Your location identifier, echoed back. Pass it as location_ref when ingesting applicants.

titlestring
statusenum
Allowed values:
organization_refstringOptional
The registry this location belongs to.
geocodedbooleanOptional

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.

addressstring or nullOptional

The stored single-line address.

createdbooleanOptional

False when the location already existed and this call was a no-op.

payobject or nullOptional

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

warningslist of stringsOptional

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
429
Too Many Requests Error