API reference

Programmatic access to event types, bookings, availability, contacts, one-off scheduling links and webhook subscriptions. The machine-readable document behind this page is openapi.json — an OpenAPI 3.1 spec you can load into Postman, Insomnia or your own code generator.

The events Calemander sends to you are listed under Webhook events at the foot of this page. Registering an OAuth client — redirect URI rules, discovery, dynamic client registration and the scope list — is covered separately, in the developer documentation.

The /api/v1 surface of a Calemander workspace.

What a credential opens

Every endpoint is user-scoped. A credential resolves to exactly one user in one workspace, and every read is filtered to that user's own rows (WHERE user_id = ?). There is no parameter anywhere in this API for asking about a different user. The one deliberate widening is webhook subscriptions: a workspace admin also sees and manages organization-scoped subscriptions created by other members.

Which host to call

A workspace lives on its own hostname. Send requests to the origin that GET /api/v1/me reports as workspace.origin (OAuth clients are told the same thing as site_url in the token response). For the deployment's default workspace that origin is the apex domain; for every other workspace it is https://{workspace}.calemander.com.

Authentication

Two credential types, told apart by token prefix, both presented as Authorization: Bearer <token>:

• API key — cm_live_ followed by 40 hex characters. Created in the dashboard under API keys with the scopes you tick and an optional expiry; only its hash is stored, so the plaintext is shown exactly once. A key opens the workspace it was created in and no other, acts as the member who created it, and stops working when that person leaves the workspace or when it expires. Keys were reset in September 2026 when they moved to resource scopes: any key created before then no longer works and must be re-created.
• OAuth 2.0 access token — cmo_at_ prefix, issued by the authorization-code flow with PKCE. Access tokens live one hour; refresh tokens ninety days.

Both carry the same scopes and both resolve to the same {userId, scopes}, so no endpoint behaves differently depending on which one you used.

Scopes

Scopes are resource:action strings and a credential holds exactly the ones it was granted — there is no implication ladder (bookings:write does not include bookings:read; tick both). Every operation below names the scope it requires. A request whose credential lacks it is refused with 403 and a message naming the scope (Insufficient scope. Required: bookings:write).

| Scope | Opens | |---|---| | bookings:read | GET /bookings — your bookings, with each attendee's name, email and notes | | bookings:write | POST /bookings, PATCH /bookings/{id}, POST/DELETE /bookings/{id}/no-show | | event_types:read | GET /event-types | | event_types:write | POST /event-types, PATCH /event-types/{id} | | availability:read | GET /availability/{slug} | | contacts:read | GET /contacts — names, emails, phone numbers, companies | | scheduling_links:read | GET /one-off-links | | scheduling_links:write | POST /one-off-links | | webhooks:read | GET /webhooks, GET /webhooks/{id} | | webhooks:manage | POST /webhooks, DELETE /webhooks/{id} — your own subscriptions; an organization-scoped subscription additionally needs the credential's owner to be a workspace admin | | check_in:read | GET /api/check-in/sessions, GET /api/check-in/sessions/{id} (the check-in API, outside /api/v1) | | check_in:write | check-in, walk-in and undo on a session | | check_in:manage | no-show, close and reopen a session |

GET /api/v1/me needs no particular scope: any valid credential may ask what it is.

A credential never exceeds its owner's role. Scopes are checked against the member's live workspace role on every request, so a change of role applies to the next call. Nothing in this API reaches workspace settings, members or billing, whatever the credential holds. Older OAuth grants that were consented to with the legacy words read / write keep exactly the access those words opened at the time (read = every *:read above except check-in; write adds bookings:write, scheduling_links:write, webhooks:manage); the consent screen shows new grants as the resource scopes they resolve to.

Rate limiting

60 requests per minute per credential, counted in a fixed 60-second window. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (a Unix timestamp in seconds). Over the limit the API answers 429 with a Retry-After header.

Error bodies

Almost every error is {"message": "..."}. The single exception is the 429, which is {"error": "Rate limit exceeded", "retryAfter": <unix seconds>} — it is produced before routing, by the rate limiter, rather than by a handler.

Times

All timestamps are UTC. Booking times are returned as they are stored; POST /api/v1/bookings normalises the times you send to UTC before persisting them.

Endpoints

Identity

Who the calling credential belongs to.

GET /api/v1/me

Identify the calling credential

Returns the user the credential opens, the workspace it belongs to, and how it authenticated. Everything in the response is derived from the credential itself; there is no way to ask about another user.

This is the connection-test endpoint: it is what an integration calls once at connection time to check a credential is live and to build a human-readable label for the connection.

Responses

{
  "user": {
    "id": "usr_9f21",
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "slug": "ada",
    "timezone": "Europe/London",
    "role": "admin",
    "scheduling_url": "https://acme.calemander.com/ada"
  },
  "workspace": {
    "slug": "acme",
    "origin": "https://acme.calemander.com"
  },
  "auth": {
    "method": "api_key",
    "scopes": [
      "bookings:read",
      "bookings:write",
      "event_types:read"
    ]
  },
  "api_key": {
    "id": "key_1",
    "name": "Zapier",
    "prefix": "cm_live_a1b2",
    "scopes": [
      "bookings:read",
      "bookings:write",
      "event_types:read"
    ],
    "expires_at": "2027-08-01T00:00:00.000Z",
    "created_at": "2026-08-01T00:00:00.000Z"
  }
}

Event Types

The bookable meeting templates a user offers.

GET /api/v1/event-types

List event types

Requires the event_types:read scope.

The authenticated user's own event types, newest first. Soft-deleted event types are never returned. Inactive ones are excluded unless include_inactive=true.

hosts is populated only for round_robin and collective event types; a one-on-one event type reports an empty list.

Parameters

Responses

POST /api/v1/event-types

Create an event type

Requires the event_types:write scope.

Creates an event type owned by the authenticated user, through the same validator the dashboard's form uses (slug rules, length limits, member checks, plan caps). The 201 body is the created event type in the same shape GET /api/v1/event-types returns.

On a plan whose active-event-type cap is full, the event type is created switched off rather than refused, and the body carries deactivatedByPlan: true with planMessage — surface that to the user, because an inactive event type is a booking page that simply does not exist.

A new group event type (maxSeats above 1) on a plan with check-in starts with a 10-minute auto-close and credits spent at attendance; on other plans, or for a one-on-one, it starts with no auto-close and booking-time credits. Pass autoCloseMinutes / creditTiming to set them explicitly.

Request body (required)

{
  "name": "Morning Flow",
  "slug": "morning-flow",
  "durationMinutes": 60,
  "maxSeats": 12
}

Responses

PATCH /api/v1/event-types/{id}

Update an event type

Requires the event_types:write scope.

Changes only the fields present in the body, on one of the authenticated user's own event types. An event type that exists but belongs to another member is 404, the same as one that does not exist. The 200 body is the updated event type in the GET /api/v1/event-types shape.

Parameters

Request body (required)

{
  "name": "Evening Flow",
  "isActive": true
}

Responses

Bookings

Scheduled meetings: list, create, and change status.

GET /api/v1/bookings

List bookings

Requires the bookings:read scope.

The authenticated user's own bookings, most recent start time first. All filters combine with AND.

Parameters

Responses

POST /api/v1/bookings

Create a booking

Requires the bookings:write scope.

Books a slot on one of the authenticated user's own event types, bypassing the public booking page.

The slot is claimed before the booking row is written, so a time that another booking already occupies is refused with 409 rather than double-booked. Claiming happens only for statuses that occupy a slot (confirmed, rescheduled, pending, payment_pending).

What this endpoint does not do: it does not send confirmation email, create a calendar event, provision a conferencing link, schedule reminders, or fire booking.created webhooks. Those belong to the public booking flow. A booking created here has meetingUrl: null and attendeeTimezone recorded as UTC, and guest emails are always empty.

The 201 body echoes the startTime and endTime as you supplied them, not as they were normalised and stored. Read the booking back if you need the stored form.

Hold-gate requirements. If the event type has a requirement whose gate is hold, this endpoint refuses with 409 unless you send allowUnpaidHold: true. The public booking page has no such escape hatch: a hold is a real seat out of availability, and the gate exists so a stranger cannot take one on a prerequisite only you can satisfy.

Request body (required)

{
  "eventTypeId": "et_intro30",
  "startTime": "2026-09-14T15:00:00Z",
  "endTime": "2026-09-14T15:30:00Z",
  "attendeeName": "Grace Hopper",
  "attendeeEmail": "grace@example.com",
  "notes": "Wants to discuss the pilot."
}

Responses

PATCH /api/v1/bookings/{id}

Update a booking's status or notes

Requires the bookings:write scope.

Changes the status and/or the attendee notes of one of the authenticated user's own bookings. Send at least one of the two fields.

The status write is conditional on the status you last read: if the booking moved underneath you, the update is refused with 409 rather than applied on top of a state you did not see.

Cancelling through this endpoint carries the same side effects as cancelling in the dashboard. Moving a booking to canceled releases its slot, deletes the linked Google, Outlook, Zoom and CalDAV entries (best effort — provider failures are logged, not surfaced), cancels pending scheduled emails, and sends the attendee the cancellation email if email is configured and the template is enabled.

Status transitions fire webhooks: booking.canceled, booking.confirmed or booking.no_show for the new status, and additionally booking.no_show_cleared whenever the booking is moving off no_show.

Parameters

Request body (required)

{
  "status": "canceled"
}

Responses

{
  "success": true,
  "id": "bkg_4c21"
}

POST /api/v1/bookings/{id}/no-show

Mark an attendee as a no-show

Requires the bookings:write scope.

Records that the attendee did not show up, moving the booking to no_show. The request takes no body — the booking is named in the path.

Only a confirmed booking whose start time has already passed can be marked: a no-show is an observation about a meeting that happened, so a booking in any other status, or one still in the future, is refused with 400.

This is the same operation the dashboard performs, and it is deliberately not the same as PATCH /api/v1/bookings/{id} with status: no_show. It fires the booking.no_show webhook *and* runs the host’s booking.no_show automation rules, exactly as a mark made in the dashboard does.

Parameters

Responses

{
  "success": true,
  "id": "bkg_4c21",
  "status": "no_show"
}

DELETE /api/v1/bookings/{id}/no-show

Clear an attendee’s no-show mark

Requires the bookings:write scope.

Takes a no-show mark back, returning the booking to confirmed. A booking not currently marked no_show is refused with 400.

Clearing is its own operation rather than a plain status write because it is its own event to a subscriber: it fires booking.no_show_cleared, so whatever acted on the original booking.no_show learns the mark was withdrawn. Automations do not re-run — there is no un-sending an email an automation already sent.

Parameters

Responses

{
  "success": true,
  "id": "bkg_4c21",
  "status": "confirmed"
}

POST /api/v1/bookings/{id}/retime-link

Mint a re-time link

Requires the bookings:write scope.

For a released hold whose link expired, or one you want to hand over another way. Minting replaces any earlier link for that booking, and nothing is emailed — you decide how it reaches the person.

Only a hold the release rule ended can be re-timed. A booking you cancelled yourself gets a one-off scheduling link instead.

Parameters

Request body

Responses

Availability

Bookable slots for one event type on one date.

GET /api/v1/availability/{slug}

List bookable slots for one date

Requires the availability:read scope.

Bookable start/end pairs for one event type on one calendar date, in UTC.

Slots account for the owner's weekly availability rules (or that date's overrides, which take precedence), existing bookings, the event type's buffers, minimum notice and slot interval, and the owner's booking-frequency caps. An empty slots array is a normal answer: it means the date is fully booked, capped, overridden closed, or has no rules for that weekday.

Results are cached briefly per slug and date.

Parameters

Responses

{
  "slots": [
    {
      "start": "2026-09-14T15:00:00.000Z",
      "end": "2026-09-14T15:30:00.000Z"
    },
    {
      "start": "2026-09-14T16:00:00.000Z",
      "end": "2026-09-14T16:30:00.000Z",
      "best": true
    }
  ]
}

Contacts

People who have booked with this user.

GET /api/v1/contacts

List contacts

Requires the contacts:read scope.

The authenticated user's own contacts, newest first.

Parameters

Responses

One-Off Links

Single-use scheduling links minted for one invitee.

GET /api/v1/one-off-links

List one-off scheduling links

Requires the scheduling_links:read scope.

The authenticated user's own one-off links, newest first.

Not paginated. The response is capped at the 100 most recent links and there is no page, limit or total.

Known behaviour: a link whose event type has since been soft-deleted is still listed here. The link itself stops working — booking it returns 404 — but it remains in this listing.

Parameters

Responses

POST /api/v1/one-off-links

Mint a one-off scheduling link

Requires the scheduling_links:write scope.

Creates a scheduling link that stops accepting bookings after max_uses bookings — one, by default. Built for post-payment automation: mint a link for a single customer, send it to them, and let it retire itself.

Identify the event type by event_type_id or event_type_slug; send at least one. Either way it must be an active, non-deleted event type owned by the authenticated user.

The 201 body is deliberately narrow: it does not repeat the raw token, the use count, or the creation timestamp. Call GET /api/v1/one-off-links for the full record.

Request body (required)

{
  "event_type_slug": "onboarding-call",
  "label": "Order 10482",
  "max_uses": 1
}

Responses

{
  "id": "9f2c41ab7d5e4c0f8b1a",
  "url": "https://acme.calemander.com/book/6f1d7c22-0b3e-4a91-9a4c-1f0e8b2d3c44",
  "label": "Order 10482",
  "expires_at": null,
  "max_uses": 1
}

Webhooks

Subscriptions that deliver booking events to your endpoint.

GET /api/v1/webhooks

List webhook subscriptions

Requires the webhooks:read scope.

Subscriptions the authenticated user can see: their own, plus — if they are a workspace admin — every organization-scoped subscription in the workspace regardless of who created it. Newest first.

Not paginated: every visible subscription is returned in one array.

Responses

POST /api/v1/webhooks

Create a webhook subscription

Requires the webhooks:manage scope.

Subscribes an HTTPS endpoint to one or more events.

The signing secret is returned only here, on creation. It is never included in any later response, and there is no way to read it back or rotate it — to change it, delete the subscription and create another.

There is no update endpoint by design. Delete and recreate.

Request body (required)

{
  "url": "https://hooks.example.com/calemander",
  "events": [
    "booking.created",
    "booking.canceled",
    "booking.rescheduled"
  ],
  "scope": "user",
  "payload_format": "calemander"
}

Responses

{
  "id": "wh_123",
  "url": "https://hooks.example.com/calemander",
  "events": [
    "booking.created",
    "booking.canceled",
    "booking.rescheduled"
  ],
  "scope": "user",
  "payload_format": "calemander",
  "is_active": true,
  "created_at": "2026-08-29T09:14:22Z",
  "secret": "0f1c9d6a-8b52-4c1e-9f7a-2d3b4c5e6f70"
}

GET /api/v1/webhooks/{id}

Fetch one webhook subscription

Requires the webhooks:read scope.

A subscription the authenticated user manages: their own, or — for a workspace admin — any organization-scoped one.

A subscription that exists but that this user may not manage returns 404, the same as one that does not exist.

This response omits payload_format, which the list and create responses both include. Read it from GET /api/v1/webhooks if you need it. The signing secret is never returned here.

Parameters

Responses

DELETE /api/v1/webhooks/{id}

Delete a webhook subscription

Requires the webhooks:manage scope.

Removes the subscription permanently. Same visibility rule as the fetch: a subscription this user does not manage returns 404.

Parameters

Responses

{
  "success": true
}

Theme

The booking page's appearance, and the proposals that come from reading a website.

GET /api/v1/theme

Read the booking page theme

Requires the theme:read scope.

The six structured theme columns for the authenticated user. custom_css is never returned.

Responses

PATCH /api/v1/theme

Change the booking page theme

Requires the theme:write scope.

Writes only the fields you send; anything absent keeps its stored value. The merged result is validated the same way the dashboard validates it, so a font outside the catalog, a malformed color or a radius above 32px is refused.

A body containing custom_css is refused with 400 and code: custom_css_not_writable_via_api — never silently dropped.

Request body (required)

Responses

POST /api/v1/theme/match

Read a website and propose a theme from it

Requires the theme:write scope.

Fetches the page at url and its stylesheets, and returns colors, a font, a button shape and a logo candidate, stored as a proposal you can apply. Nothing changes until you apply it.

The read is bounded: five a minute and forty a day per workspace, shared with the dashboard. A read that fails is not an error — the 200 body carries ok: false and a fetch_note saying whether the address was refused, unreachable or blocked.

The site is fetched with no cookies, no credentials and no headers of yours, and nothing read from it becomes CSS.

Request body (required)

Responses

GET /api/v1/theme/proposals

List theme proposals

Requires the theme:read scope.

This workspace's own match history, newest first. Summaries only; read one proposal for its palette and fields.

Parameters

Responses

GET /api/v1/theme/proposals/{id}

Read one theme proposal

Requires the theme:read scope.

The stored palette and proposal. A proposal belonging to another user reads as 404.

Parameters

Responses

POST /api/v1/theme/proposals/{id}/apply

Apply a theme proposal

Requires the theme:write scope.

Writes the accepted fields to the booking page and snapshots what was there, so the change can be reverted exactly. Send fields to accept some of them; omit it to accept every field the proposal carries.

overrides.custom_css is refused with 422 and code: custom_css_not_writable_via_api. A proposal never carries custom CSS and this path cannot write it.

Parameters

Request body

Responses

POST /api/v1/theme/proposals/{id}/revert

Undo an applied theme proposal

Requires the theme:write scope.

Restores the theme snapshot taken when the proposal was applied, exactly as it was, and marks the proposal reverted. Only an applied proposal can be reverted.

Parameters

Responses

POST /api/v1/theme/preview-link

Mint a theme preview link

Requires the theme:write scope.

Reads a website and returns a signed, short-lived link showing a demo workspace's real service menu in that site's colors, watermarked as an example. Nothing is stored and no booking made on it is real.

The read costs one unit from the match budget and one from the preview budget. A deployment with no demo workspace answers 503.

Request body (required)

Responses

Requirements

The prerequisites a booking is held on, and the clears that release it.

POST /api/v1/checkout-claims

Mint a reservation token for your own checkout

Requires the bookings:write scope.

Asks for a short-lived, signed token that lets ONE customer reserve ONE time on ONE event type from inside your own checkout.

Call it server-side, when the customer reaches your checkout and you are about to show them the time picker. Put the returned embedUrl in an iframe; when the customer picks a time the booker reserves it immediately — off your calendar, no email, no webhook — and posts calemander:claimCreated to your page with the booking id to carry on your payment.

The event type must carry a requirement marked as the one your checkout reserves against ("Payment is collected on my site"), and must not also carry a Calemander price, deposit or card-on-file setting: two rails charging one booking is two sources of truth for the same money.

claimTtlSeconds is how long the RESERVATION lasts once it is made — set it to the life of your own payment session. A reservation that outlives the session holds inventory nobody can buy; one that dies before it produces 410s when the payment finally lands. tokenTtlSeconds is the different, shorter clock on how long this token may be used to START a reservation.

Bind attendeeEmail whenever you know it: it is what stops a token leaked out of one customer's browser reserving a time for somebody else. Do not log the token, and do not mint one before you know the customer is on the page.

Request body (required)

Responses

POST /api/v1/bookings/{id}/external-payment

Record a payment you took on your own site

Requires the requirements:write scope.

Tells Calemander that the payment for a reserved time cleared. Call it from your payment webhook, or wherever you learn the money arrived.

Calemander charged nobody: it records "reported paid by <provider> under <reference>", marks the booking paid, fires booking.created at THIS moment — not when the time was reserved — and then either confirms the booking or holds it on whatever else you require. provider is a label of your own choosing (stripe, square, invoice, manual, anything); nothing branches on it.

Send an Idempotency-Key. Your provider will deliver its webhook more than once, and with the key the second delivery gets the first answer verbatim, status code included, with nothing running twice.

A 410 means the reservation ended before the payment arrived and the time may already be sold. The payment is still recorded, so the audit trail is honest; Calemander does not resurrect the booking and never refunds anything. What to tell the customer is yours to decide — the pattern that works is a one-off scheduling link and one true sentence.

The generic requirement clear endpoint refuses the checkout requirement of a live reservation with 409 record_payment_instead: "paid" is a money fact with a provider, an amount and a currency, and it belongs on the booking.

Parameters

Request body (required)

Responses

POST /api/v1/bookings/{id}/release-claim

Give a reservation back

Requires the bookings:write scope.

Puts a reserved time back on sale now, rather than waiting for it to expire.

Optional: a customer who picks again replaces their own reservation, and an unpaid one expires on its own. Use this when your checkout KNOWS the customer left.

released: false is not an error — it means the reservation was already gone, or already paid for. A payment landing in the same instant wins, and the time stays sold.

Parameters

Responses

GET /api/v1/bookings/{id}/requirements

List what a booking is still waiting on

Requires the requirements:read scope.

The booking’s requirement checklist in the order an attendee reads it, with the full provenance of everything already satisfied.

Only cleared and waived count as met. A booking whose outstanding is 0 is confirmed; one with rows still open is held — its time is taken out of availability, and there is no calendar event, no reminder and no confirmation email until the last requirement clears.

A booking with an empty list is not a requirements booking and behaves exactly as it always has.

Parameters

Responses

POST /api/v1/bookings/{id}/requirements/{key}/clear

Clear a requirement

Requires the requirements:write scope.

Records that a prerequisite has been met, from the system that actually knows. If it was the last one, the booking confirms itself: calendar event, confirmation email, reminders, and the booking.confirmed webhook, with nobody clicking anything.

Send externalRef: the identifier your system matched on. How the clear is classified is not yours to send. There is no clearMethod field and there must not be — a caller that could name its own method could dress a guess up as a county’s reference. A requirement that was outstanding records system_reference; one the attendee had already submitted records attendee_evidence with verifiedBy: "api", and referenceMatched is true when your reference is the one they typed.

Clearing an already-cleared requirement is a 200 no-op: the answer is already yes. Clearing on a canceled or released booking is also a 200 — the clear is recorded, the booking is not resurrected, and the response says what the booking’s status actually is.

Idempotency. Send an Idempotency-Key header and the write runs once: a replay with the same key returns the first response verbatim rather than acting again, so a retry loop cannot fire booking.confirmed twice. A clear carrying an externalRef that already sits on a cleared requirement of the same booking is a no-op regardless of the header.

Parameters

Request body

Responses

POST /api/v1/bookings/{id}/requirements/{key}/waive

Waive a requirement

Requires the requirements:write scope.

Decides that this booking does not need the prerequisite after all. Waiving satisfies, so it can be the move that confirms the booking.

note is required. A waiver is a person overriding a gate, and a waiver with no reason is an unexplained hole in the record — it is the one line a host reading the booking six weeks later needs. The note is host-facing and is never rendered to the attendee.

Idempotency. Send an Idempotency-Key header and the write runs once: a replay with the same key returns the first response verbatim rather than acting again, so a retry loop cannot fire booking.confirmed twice. A clear carrying an externalRef that already sits on a cleared requirement of the same booking is a no-op regardless of the header.

Parameters

Request body (required)

Responses

POST /api/v1/bookings/{id}/requirements/{key}/verify

Verify what the attendee submitted

Requires the requirements:write scope.

Says yes to a reference the attendee supplied themselves. Only a submitted requirement can be verified; anything else is a 409 naming its state, because a caller that meant to verify and instead cleared an untouched requirement would have recorded something stronger than what happened.

The attendee submitting a reference satisfies nothing on its own: it is a claim about the outside world, and a booking must never confirm on a claim. This is the second party saying the claim is true. Send your own externalRef and referenceMatched comes back true when it is the same one they typed — the strongest signal the system holds. When the two disagree the requirement still clears and referenceMatched stays false: a person can mistype while the outside system approves the right file, and a hard block there would hold a correct booking hostage to a typo. It is surfaced, not enforced.

Idempotency. Send an Idempotency-Key header and the write runs once: a replay with the same key returns the first response verbatim rather than acting again, so a retry loop cannot fire booking.confirmed twice. A clear carrying an externalRef that already sits on a cleared requirement of the same booking is a no-op regardless of the header.

Parameters

Request body

Responses

POST /api/v1/bookings/{id}/requirements/{key}/send-back

Send an attendee’s submission back

Requires the requirements:write scope.

Rejects a reference the attendee supplied. The requirement moves to failed, which does not satisfy, so the booking stays held — and the host sees why, instead of an outstanding row that looks like nobody has looked at it.

note is required and is written for the host; it is never shown to the attendee. Sending back also invalidates the attendee’s outstanding self-serve links, so they open a fresh one and retype. The ordinary cause of a rejection is a mistyped digit, and that should cost one email rather than a support ticket.

Idempotency. Send an Idempotency-Key header and the write runs once: a replay with the same key returns the first response verbatim rather than acting again, so a retry loop cannot fire booking.confirmed twice. A clear carrying an externalRef that already sits on a cleared requirement of the same booking is a no-op regardless of the header.

Parameters

Request body (required)

Responses

POST /api/v1/requirements/preclear

Record a clear that arrived before the booking

Requires the requirements:write scope.

Files a clear against a person rather than a booking, for when the outside system knows before the attendee has picked a time.

The case this exists for: an approval lands while the customer has still not booked. There is no requirement row to clear, and asking your integration to poll until one appears would trade a fact it already holds for a schedule. Post it here instead. When a booking is later created for a matching subject, the requirement is written already cleared, carrying this call’s provenance, and the booking confirms on the spot.

subject needs at least one of attendeeEmail or externalRef — a pre-clearance naming nobody would not mean "this customer is cleared", it would mean "clear the next booking that arrives". A pre-clearance is single-use and expires (180 days unless the requirement’s definition says otherwise), because an approval about one file should not confirm a second booking, and should not still be confirming bookings after the thing it attested to has lapsed.

Idempotency. Send an Idempotency-Key header and the write runs once: a replay with the same key returns the first response verbatim rather than acting again, so a retry loop cannot fire booking.confirmed twice. A clear carrying an externalRef that already sits on a cleared requirement of the same booking is a no-op regardless of the header.

Request body (required)

Responses

GET /api/v1/event-types/{id}/requirements

Read an event type’s requirements

Requires the requirements:read scope.

The prerequisites this event type asks for. Each one is copied onto every booking made on it, so editing the wording here changes what future attendees are asked and leaves what past attendees agreed to exactly as it was.

Host approval is not listed: it is the event type’s own "requires confirmation" setting, and giving it a second home here is how the two would come to disagree.

Parameters

Responses

PUT /api/v1/event-types/{id}/requirements

Set an event type’s requirements

Requires the requirements:write scope.

Replaces the whole list. A definition that is absent from the array is deactivated rather than deleted — bookings already held on it keep their own copy of the wording, and deleting the template would strand them.

An empty array clears them. host_approval is refused as a key. allowAttendeeEvidence is only valid on an external requirement, and an attendee_acknowledgement needs the ackText the attendee is agreeing to.

Parameters

Request body (required)

Responses

Questions

Questions an event type asks, and the answers a booking carries. A question is asked at booking or after it; an after-booking question is answered by the attendee on their own booking page and never holds anything up.

GET /api/v1/event-types/{id}/questions

List an event type’s questions

Requires the event_types:read scope.

Both stages by default, in the order they are shown. Pass ?stage=after_booking to list only the questions the attendee answers on their own booking page, or ?stage=at_booking for the booking form's.

Parameters

Responses

POST /api/v1/event-types/{id}/questions

Add a question to an event type

Requires the event_types:write scope.

stage defaults to at_booking, which is the booking form. Set it to after_booking and the question never appears on the form; the attendee answers it on their booking page, whenever they are ready, and isRequired then means one reminder rather than a gate.

A condition may only point backwards in stage: a booking-form question cannot depend on an after-booking answer, because that answer does not exist when the form is rendered.

Parameters

Request body (required)

Responses

PATCH /api/v1/event-types/{id}/questions/{questionId}

Update a question

Requires the event_types:write scope.

Any subset of the create body. Moving a question to after_booking while a booking-form question depends on it is refused with condition_stage_order, which is the same rule read from the other end. Conditions name option TEXT: renaming an option rewrites every rule that named it, and removing an option another question's condition still names is refused with 422 unless the body sets detachConditions to true.

Parameters

Request body (required)

Responses

DELETE /api/v1/event-types/{id}/questions/{questionId}

Remove a question

Requires the event_types:write scope.

A soft delete: the question stops being asked, and every answer already given to it stays readable on the bookings that carry it. A question that another question's condition depends on is refused with 422; pass ?detachConditions=true to drop those rules and delete it anyway.

Parameters

Responses

GET /api/v1/bookings/{id}/responses

Read a booking’s answers

Requires the bookings:read scope.

Every question the event type asks, answered or not, in the order they are shown. A question with answer: null has not been answered; answeredAt is null for an answer given on the booking form.

Parameters

Responses

PUT /api/v1/bookings/{id}/responses

Write a booking’s answers

Requires the bookings:write scope.

A merge: only the questions named in the body change, and null clears an answer. Values are validated against each question's type and options exactly as the booking form validates them. Any stage may be written — correcting a typo in a booking-form answer is legitimate — and the write is recorded as answered by api.

Idempotent by construction, so no Idempotency-Key is needed: sending the same body twice leaves the same answers and fires one booking.responses_updated, because the second save changes nothing.

Parameters

Request body (required)

Responses

Webhook events

These are the events Calemander sends to you. Subscribe with POST /api/v1/webhooks; the signing secret is returned once, on creation.

booking.canceled

A booking was cancelled

Fires when a booking is cancelled by the invitee, by the host, as part of cancelling a recurring series, when a pending booking is rejected, or through PATCH /api/v1/bookings/{id}. canceledBy and cancellationReason are populated where they were recorded.

booking.checked_in

An attendee was checked in

Fires when a confirmed booking is checked in to its session — by staff on the roster, by the attendee at the door or from their phone, or by a walk-in booking. The booking keeps status: confirmed; the payload adds checkedInAt and checkedInBy (staff, self, door or auto). Undoing a check-in sends nothing.

booking.confirmed

A pending booking was approved

Fires when a booking that required confirmation is approved by the host, when payment completes for a paid event type, or when PATCH /api/v1/bookings/{id} moves a booking to confirmed.

Calendly-format subscribers never receive this event — Calendly has no approval step and therefore no equivalent name, so nothing is sent rather than something the receiver cannot dispatch.

booking.created

A booking was made

Fires when a booking is created through the public booking flow, including recurring series. It does not fire for bookings created through POST /api/v1/bookings.

booking.held

A booking is held on unmet requirements

Fires when a booking takes a time but cannot be confirmed yet: its seat is out of availability and one or more of its requirements is neither cleared nor waived. The payload carries the requirement list.

There is no calendar event and no confirmation email at this point, and the attendee has been told so. booking.confirmed follows when the last requirement clears.

Calendly-format subscribers never receive this event — Calendly has no held booking and therefore no equivalent name, so nothing is sent rather than something the receiver cannot dispatch.

booking.no_show

An invitee was marked as a no-show

booking.no_show_cleared

A no-show mark was taken back

Fires when a booking leaves the no_show status. When the change also produces another event — a no-show booking moved straight to canceled, say — both are delivered.

booking.rescheduled

A booking moved to a new time

Fires when a booking is rescheduled. The payload carries the new startTime/endTime and the previous ones as oldStartTime/oldEndTime; status is confirmed.

On the calendly format this single event becomes two deliveries, matching what Calendly itself sends: an invitee.canceled for the old time with rescheduled: true, followed by an invitee.created for the new time carrying old_invitee.

{
  "event": "booking.rescheduled",
  "payload": {
    "eventTypeId": "et_intro30",
    "eventTypeSlug": "intro-30",
    "eventTypeName": "Intro call",
    "durationMinutes": 30,
    "locationType": "google_meet",
    "meetingUrl": "https://meet.google.com/abc-defg-hij",
    "attendeeNotes": null,
    "attendeeTimezone": "Europe/London",
    "host": {
      "name": "Ada Lovelace",
      "email": "ada@example.com"
    },
    "answers": [],
    "bookingCreatedAt": "2026-08-20T11:02:00Z",
    "canceledBy": null,
    "cancellationReason": null,
    "paymentStatus": null,
    "guestEmails": [],
    "joinUrl": "https://ada.calemander.com/join/bkg_4c21/eyJ2IjoxLCJ0Ijo...",
    "oneOffLinkId": null,
    "oneOffToken": null,
    "bookingId": "bkg_4c21",
    "eventSlug": "intro-30",
    "eventName": "Intro call",
    "startTime": "2026-09-15T15:00:00Z",
    "endTime": "2026-09-15T15:30:00Z",
    "oldStartTime": "2026-09-14T15:00:00Z",
    "oldEndTime": "2026-09-14T15:30:00Z",
    "attendeeName": "Grace Hopper",
    "attendeeEmail": "grace@example.com",
    "status": "confirmed"
  },
  "timestamp": "2026-08-29T09:14:22.115Z"
}

requirement.cleared

A requirement was satisfied

Fires when one requirement moves to cleared or waived. The payload carries the full provenance — clearMethod, clearedBy, verifiedBy, referenceMatched, externalRef and evidenceRef — so a subscriber can hold a weakly-cleared booking to a different standard than a strongly-cleared one without a second API call.

It fires once per actual move. A replay, an already-cleared requirement and a repeated reference all change nothing and send nothing. When the clear was the last one, booking.confirmed follows.

Calendly-format subscribers never receive this event.

requirement.submitted

An attendee supplied a reference

Fires when an attendee submits evidence for a requirement — the county application number they are holding, say. The requirement moves to submitted and the booking stays held: this is a claim about the outside world, not a fact about it.

This is the event an integration subscribes to in order to close the loop by itself. Your system hears the reference the moment the attendee types it, can go and match on it, and can then clear the requirement — at which point the two independent sources agree and the record says so.

Calendly-format subscribers never receive this event.

booking.released

A held booking was released

Fires when a booking held on outstanding requirements reaches its release time with something still uncleared. The booking becomes status: canceled with cancellation_reason naming what was outstanding, and the seat goes back on sale. The payload adds outstanding (the labels still unmet), releasedAt, rebookUrl, and refundIssued, which is always false — releasing a hold never refunds, and whether money is returned is the host's decision rather than this event's. A requirement that clears after this fires is recorded on the released booking and does not un-cancel it.

booking.responses_updated

An after-booking answer changed

Fires whenever an answer to a question the event type asks after booking actually changes — from the attendee's own booking page or from PUT /bookings/{id}/responses. Never fires for a save that changed nothing. The payload adds changedQuestionIds (the ids that moved), answeredBy (attendee, host or api), responses (the full set for the booking, both stages, each with stage and answeredAt), and detailsUrl. There is no Calendly-compatible name for this event, so compat subscribers do not receive it. A required after-booking question never changes a booking's status, so this event never coincides with one.

routing_form_submission.created

A routing form was submitted

Fires when someone submits a routing form. Submissions are not stored, so submissionId identifies this delivery rather than a row you can fetch later. This payload receives none of the booking enrichment fields.

standby.offered

A freed seat was offered to someone on standby

Fires when a seat comes free on a full class and the person at the front of the standby line is offered it. One person per seat: nobody else is offered the same seat while this offer is open. offerExpiresAt is when the hold ends, which is the event type's standbyOfferMinutes or five minutes when the class starts within 30. An offer that runs out sends nothing; the entry goes back to the end of the line.

standby.promoted

Someone on standby got the seat

Fires when a standby entry becomes a booking — they accepted an offer, the host promoted them from the roster, or a close-out gave them a seat freed by a no-show. bookingId is the booking that now exists; the ordinary booking.created fires for it as well.

Schemas

Booking

BookingRequirement

One prerequisite on one booking, with the full record of how it reached its state.

BookingRequirementList

BookingResponse

BookingResponseList

BookingWebhookEnvelope

The calemander wire format: one message per event. Signed with HMAC-SHA256 over the raw body, hex-encoded, in X-Webhook-Signature; X-Webhook-Timestamp echoes the timestamp below. Subscribers on the calendly format receive Calendly's own envelope and a Calendly-Webhook-Signature: t=<unix>,v1=<hex> header instead, where v1 is HMAC-SHA256 over <t>.<raw body>.

BookingWebhookPayload

The eight base fields are always present. The rest are enrichment, loaded from the booking at fire time — if that lookup fails the message still ships, carrying the base fields alone. Treat every enrichment field as optional.

Contact

Error

The error shape used by every endpoint except the 429.

EventType

EventTypeHost

EventTypeRequirement

A requirement as defined on an event type — the template copied onto every booking.

EventTypeRequirementList

EventTypeWrite

Body of POST /api/v1/event-types (where name, slug and durationMinutes are required) and PATCH /api/v1/event-types/{id} (where every field is optional and only the fields present are changed). Unknown fields are refused with 400.

These are the fields the dashboard editor writes that the API exposes. Payment settings (mode, price, deposit, fees), buffers, booking limits, questions and redirects are configured in the dashboard.

Identity

NoShowResult

The outcome of marking or clearing a no-show, including the status the booking now carries.

OneOffLink

PageNumber

The page that was served.

Type: integer

Preclearance

Question

One question on an event type.

QuestionInput

QuestionList

RateLimitError

Only returned by the 429. Produced by the rate limiter before routing, which is why it does not use message.

RequirementWriteResult

The same shape for every requirement write: what the requirement is now, what the booking is now, and how much is left.

RoutingFormSubmissionPayload

Scope

A resource:action scope. See Scopes in the introduction for what each opens.

One of:

• bookings:read
• bookings:write
• event_types:read
• event_types:write
• availability:read
• contacts:read
• scheduling_links:read
• scheduling_links:write
• webhooks:read
• webhooks:manage
• check_in:read
• check_in:write
• check_in:manage
• theme:read
• theme:write
• requirements:read
• requirements:write

SitePalette

What was found on the site: colors as #rrggbb, font names as the site wrote them, an integer radius, and a logo URL. No markup and no CSS text is stored or returned. The font name and the logo URL are the only strings here copied from a third party; treat them as data.

Type: object

StandbyWebhookPayload

A standby entry's state changed. Deliberately not a booking payload: an offer has no booking behind it and may never get one.

Theme

The booking page's structured appearance. custom_css is deliberately absent: the API neither returns it nor accepts it, and it is edited only on the Appearance page.

ThemeProposal

What is offered for the booking page: one value per theme field with a confidence and a one-line reason. There is no custom_css field and there cannot be one.

Type: object

ThemeProposalSummary

One row of match history.

TimeSlot

Total

Rows matching the filter, across all pages.

Type: integer

TotalPages

Pages available at this limit.

Type: integer

WebhookEventName

One of:

• booking.created
• booking.canceled
• booking.rescheduled
• booking.confirmed
• booking.no_show
• booking.no_show_cleared
• booking.checked_in
• booking.held
• requirement.submitted
• requirement.cleared
• booking.released
• booking.responses_updated
• routing_form_submission.created
• standby.offered
• standby.promoted

WebhookSubscription

A subscription as returned by the list and create endpoints.

WebhookSubscriptionDetail

A subscription as returned by GET /api/v1/webhooks/{id}. Note the absence of payload_format.