> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.confirm.global/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.confirm.global/_mcp/server.

# 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`](/partner-api/organizations/create-organization) 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`:

```json
{
  "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`](/partner-api/candidates/create-candidate), `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`.

```json
{
  "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`](/partner-api/organizations/create-calendar-invite) with the address of whoever manages the registry's interview schedule:

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

```json
{
  "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.