Calendar

Screening calls in a workspace are held until it has a connected calendar. An applicant who passes screening is sent a link to book an interview, and that link books against the workspace calendar. With no calendar there is nothing to book against, so CONFIRM queues the calls and holds them.

A workspace you provision with POST /organizations starts without a calendar. Connecting one is a one-time step per registry, and nobody needs a CONFIRM login to do it.

How to tell

Organization responses carry calendar.connected, on both POST /organizations and GET /organizations:

{
  "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."
  ]
}

While connected is false, POST /organizations adds that warning. In the rare case the check itself fails, calendar is left out of the response rather than guessed.

Applicants show it too. On POST /candidates, screening_hold is "calendar_not_connected" when screening is enqueued and the workspace has no connected calendar. With location_refs, each entry in applications has its own screening_hold. In every other case it is null.

{
  "candidate_id": "9f4c2e81-6d3a-4b7e-a1c2-8e5f0d743b16",
  "application_id": "51c0a7de-2f18-4a3e-96b7-1d0c8b2e4a77",
  "external_ref": "cl_app_84321",
  "deduped": false,
  "screening": "enqueued",
  "screening_hold": "calendar_not_connected",
  "portal_url": "https://app.confirm.global/c/suncoast-nurse-registry/candidates/9f4c2e81-6d3a-4b7e-a1c2-8e5f0d743b16",
  "webhook_url": "https://hooks.example.com/confirm/8f2c41aa-1d64-4f0b-9c33-2a7e5b104db8"
}

The applicant is accepted either way. A held call is still queued; it is not dropped.

Send a calendar-connect link

Call POST /organizations/{ref}/calendar-invite with the address of whoever manages the registry’s interview schedule:

curl https://api.confirm.global/partner/v1/organizations/cl_biz_4471/calendar-invite \
  -H "Authorization: Bearer cfk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "scheduling@suncoastnurses.com",
    "first_name": "Dana",
    "last_name": "Whitfield"
  }'

{
  "invite_url": "https://app.confirm.global/calendar-connect/4b9e2c71-0d5a-4f83-9a16-7e2c5d8b1f40",
  "email": "scheduling@suncoastnurses.com",
  "expires_at": "2026-10-13T15:20:41.512Z",
  "emailed": true
}

CONFIRM emails the link. To deliver it yourself, for example inside your own product, send "send_email": false and use invite_url. emailed tells you whether the email went out. It is also false if sending failed, in which case the link still works and you should deliver it yourself.

• 201 or 200. 201 is a new link. 200 returns the link already pending for that address in this workspace, with its original expires_at, and emails it again unless send_email is false. Calling it twice never creates two links for one address.
• 7 days, one use. After that, call the endpoint again for a fresh link.
• 409 email_has_account. The address already has a CONFIRM account. An account belongs to one workspace, so the link could not be used. Invite a different address. Someone who already has a regular account in this workspace can connect a calendar themselves from Settings → Integrations in the portal.
• 404 unknown_organization_ref. No registry with that ref belongs to your partner account.

What the invitee does

They open the link and connect their Google or Outlook calendar. That’s all: no password, no portal sign-in. If the workspace has no calendar yet, the one they connect becomes the workspace calendar, and interviews are booked on it.

What happens next

Held screening calls go out once a calendar is connected. You don’t need to re-send any applicants. Calls are re-checked periodically, so allow up to about half an hour for them to start. They still respect the usual calling hours.

GET /organizations reports calendar.connected: true from then on, and new applicants come back with screening_hold: null.

If the workspace calendar is later disconnected or its access stops working, and no one else in the workspace has a connected calendar to take its place, calendar.connected goes back to false and screening calls are held again until one is connected.