Provision a registry workspace

Returns the workspace identifier — the one-per-business value you store and use to recognise and build CONFIRM links.

Idempotent on external_ref: calling it again returns the existing workspace with created: false and the same body, so your job never has to branch on whether it has run before.

A dedicated phone number with caller-ID registration is provisioned separately by CONFIRM, since it requires carrier registration that cannot complete synchronously.

Provisions a complete CONFIRM workspace for one of your registries: the organization, its cloned AI screening agent, and registry-branded candidate messaging. Call it when a business is created on your side, or when they enable recruiting. Returns the **workspace identifier** — the one-per-business value you store and use to recognise and build CONFIRM links. Idempotent on `external_ref`: calling it again returns the existing workspace with `created: false` and the same body, so your job never has to branch on whether it has run before. A dedicated phone number with caller-ID registration is provisioned separately by CONFIRM, since it requires carrier registration that cannot complete synchronously.

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 registry/business identifier. The key this workspace is correlated on, forever.

namestringRequired

Display name of the registry. Appears in the portal and in candidate-facing messaging.

primary_contact_emailstringOptionalformat: "email"

Registry's primary contact. Used for administrative correspondence, not candidate messaging.

detailsobjectOptional

Optional profile enrichment used in screening context and job copy.

Response

The registry was already provisioned; the existing workspace is returned.

organization_idstringformat: "uuid"

CONFIRM's identifier for the registry.

external_refstring

Your registry/business identifier, echoed back.

namestring

workspacestring

The workspace identifier — store this per business. It is the {workspace} segment of every CONFIRM deep link.

workspace_urlstringformat: "uri"

Base URL of the registry's workspace.

createdbooleanOptional

False when the registry was already provisioned and this call was a no-op.

statusstringOptional

warningslist of stringsOptional

Non-fatal notes about the provisioning run, when any apply.

Errors

400

Bad Request Error

401

Unauthorized Error

429

Too Many Requests Error

Returns the workspace identifier — the one-per-business value you store and use to recognise and build CONFIRM links.

Idempotent on external_ref: calling it again returns the existing workspace with created: false and the same body, so your job never has to branch on whether it has run before.

A dedicated phone number with caller-ID registration is provisioned separately by CONFIRM, since it requires carrier registration that cannot complete synchronously.

$	curl -X POST https://api.confirm.global/partner/v1/organizations \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"external_ref": "cl_biz_4471",
>	"name": "Suncoast Nurse Registry",
>	"primary_contact_email": "admin@suncoastnurses.com",
>	"details": {
>	"timezone": "America/New_York",
>	"website": "https://suncoastnurses.com"
>	}
>	}'

1	{
2	"organization_id": "string",
3	"external_ref": "cl_biz_4471",
4	"name": "Suncoast Nurse Registry",
5	"workspace": "suncoast-nurse-registry",
6	"workspace_url": "https://app.confirm.global/c/suncoast-nurse-registry",
7	"created": true,
8	"status": "active",
9	"warnings": [
10	"string"
11	]
12	}