Provision a registry workspace

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"
  }
}'

{
  "organization_id": "9f4c2e81-6d3a-4b7e-a1c2-8e5f0d743b16",
  "external_ref": "cl_biz_4471",
  "name": "Suncoast Nurse Registry",
  "workspace": "suncoast-nurse-registry",
  "workspace_url": "https://app.confirm.global/c/suncoast-nurse-registry",
  "created": true,
  "calendar": {
    "connected": false
  },
  "warnings": [
    "No calendar connected — screening calls are held until someone in this workspace connects a calendar. Use POST /organizations/{ref}/calendar-invite."
  ]
}

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.

A new workspace has no calendar, so its screening calls are held. The response carries calendar.connected. While it is false, warnings says so and screening calls in the workspace wait. Send a calendar-connect link with POST /organizations/{ref}/calendar-invite; held calls go out once a calendar is connected. See the calendar guide.

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

authobject or nullOptional

Sandbox only. Which CareLink auth server this workspace’s users sign in against. Omit it to use the default (your staging auth server in sandbox). auth: null and auth: {} both mean the default sign-in server, the same as sending base_url: null. In production it is ignored with a warning, since production workspaces always use the production auth server.

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

Workspace provisioned. Posting an external_ref that already exists returns 200 with the same workspace and created: false, so replays never create a second workspace.

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

authobjectOptional

Present when the workspace has its own auth server (sandbox), on both POST and GET. A POST that sent auth always echoes it, with base_url: null when the workspace is on the default server.

calendarobjectOptional

Whether the workspace has a connected calendar, on both POST and GET. Screening calls in the workspace are held while connected is false; connect one with POST /organizations/{ref}/calendar-invite. Left out on the rare response where the check itself could not be made, rather than guessing.

warningslist of stringsOptional

Non-fatal notes about the provisioning run, when any apply (POST only). Includes a note that screening calls are held while the workspace has no connected calendar.

Errors

400

Bad Request Error

401

Unauthorized Error

429

Too Many Requests Error