Create a location | CONFIRM Docs

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.

Idempotent on external_ref within the registry: calling it again returns the existing location with created: false.

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`. Idempotent on `external_ref` within the registry: calling it again returns the existing location with `created: false`.

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.

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

titlestringRequired

The role screened at this location.

descriptionstringOptional

Role description. Used in candidate-facing copy and screening context.

employment_typestringOptional

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.

Response

The location already existed; the existing record is returned.

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

organization_refstringOptional

The registry this location belongs to.

geocodedbooleanOptional

True when the address resolved to coordinates. False means distance screening is inactive for this location — check warnings.

addressstring or nullOptional

The stored single-line address.

createdbooleanOptional

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

warningslist of stringsOptional

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

429

Too Many Requests Error

$	curl -X POST https://api.confirm.global/partner/v1/locations \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"external_ref": "cl_loc_88213",
>	"organization_ref": "cl_biz_4471",
>	"title": "Certified Nursing Assistant — Clearwater",
>	"address": {
>	"street": "1100 Cleveland St",
>	"city": "Clearwater",
>	"state": "FL",
>	"postal_code": "33755",
>	"country": "US"
>	}
>	}'

1	{
2	"location_id": "string",
3	"external_ref": "cl_loc_88213",
4	"title": "Certified Nursing Assistant — Clearwater",
5	"status": "active",
6	"organization_ref": "cl_biz_4471",
7	"geocoded": true,
8	"address": "string",
9	"created": true,
10	"warnings": [
11	"string"
12	]
13	}