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

A credential resolves to exactly one user in one workspace, and how far it reaches inside that workspace follows that user's role, exactly as the dashboard does: a credential whose owner is a workspace admin reads and writes every host's bookings in the workspace, and one whose owner is a member only the bookings that member hosts. GET /api/v1/me reports which of the two you hold as reach. Everything that is not a booking — event types, contacts, one-off links, availability, themes — stays filtered to the credential's own rows whatever the role. The other deliberate widening is webhook subscriptions: a workspace admin also sees and manages organization-scoped subscriptions created by other members.

Reach is read from the owner's live role on every request, so promoting or demoting someone changes what their existing keys and grants do immediately, and there is no scope to tick and no key to re-create. Booking rows carry hostId and hostEmail so a workspace-wide list says whose each booking is, and GET /bookings?host= narrows one to a single host. A booking outside a credential's reach answers 404, never 403, so a member credential cannot use the API to learn which booking ids exist.

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 — the bookings within your reach (see above), with each attendee's name, email and notes | | bookings:write | POST /bookings (always on your own event types, as yourself), PATCH /bookings/{id}, POST/DELETE /bookings/{id}/no-show — the writes reach whatever your role reaches | | 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. A refusal that has a machine-readable reason also carries code next to message (slot_taken, claim_expired, record_payment_instead and so on); branch on code, not on the wording of message. A few 429s come from elsewhere and are described under the RateLimited response: an OAuth client over its own budget, a workspace minting too many checkout tokens, and the theme endpoints' site-read budgets.

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"
  },
  "reach": "workspace",
  "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 bookings within this credential's reach, most recent start time first: every host's in the workspace for an admin credential, the credential owner's own for a member. All filters combine with AND.

A booking of an event type that sells nights or days carries its stay (dates, inventory, units, charges); every other booking carries stay: null.

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. Creating is not reaching: this always books on the credential's own event type and hosts the booking as the credential's own user, whatever its role.

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, or schedule reminders. Those belong to the public booking flow. It does fire webhooks, as every other create path does: booking.created, then booking.held when the booking parks on a requirement. 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.

Stays. For an event type that sells nights or days, send stay instead of times. The booking is created confirmed (or pending when the event type requires confirmation or a requirement holds it; status may say pending, and any other status is refused with 400 stay_status_invalid), its startTime/endTime are the check-in and check-out instants, and the 201 body carries its stay. Sending times for such an event type is 400 stay_event_type; sending stay for an event type of times is 400 not_a_stay.

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 a booking within this credential's reach — any host's in the workspace for an admin credential, the credential owner's own for a member. An admin cancelling a booking someone else hosts cleans up that host's calendar and meeting and mails the attendee from their identity; the credential is recorded as the actor. 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.

Stays. This endpoint never changes a stay's dates; use POST /api/v1/bookings/{id}/stay-change. A stay's no-show goes through POST /api/v1/bookings/{id}/no-show, which sets its nights aside so the mark can be taken back, and a stay that no longer holds its nights cannot be put back by a status: both are 409 stay_status_not_supported.

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.

A credential may report the payment when its owner is a workspace admin, owns the reservation's event type, or is the host the booking is assigned to, so a round-robin booking Calemander assigned to a host other than the one whose key reserved the time still settles with that key. Any other credential gets 404 not_a_claim.

Parameters

Request body (required)

Responses

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

Lock a picked time while the customer pays

Requires the bookings:write scope.

Takes the time for the length of a payment session, immediately BEFORE you create that session.

Only meaningful on an event type with claimExclusive: false, where a customer's pick reserves nothing and the time stays on sale. This is what turns that pick into a reservation, and it is the reason a customer never pays for a time somebody else already took: a caller that loses here has charged nobody.

409 slot_taken means the time went while the customer was typing. The pick is cancelled, nothing has been charged, and you send them back to the picker.

The deadline is written to the claim's own expiry, so the time comes back on sale by itself if nobody pays, and release-claim gives it back sooner. Locking again extends the deadline and never shortens it.

On an event type with claimExclusive: true this is a no-op that reports the deadline the reservation already has, so you may wire the call once and leave it wired.

Parameters

Request body

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.

Parameters

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. A requirement bound to this question (evidenceQuestionId) is stranded by a move to after_booking or a change to a type nobody types into; that is refused with 422 requirement_binding_in_use unless the body sets detachRequirements 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. A question a requirement takes its reference from is refused the same way; pass ?detachRequirements=true to unhook the binding and delete it anyway, after which the attendee is asked for the reference on the checklist instead.

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, unless purgedAt is set — then it was answered and the answer has since been deleted under the workspace's intake retention policy. 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

Stays

Event types that sell nights or days instead of times: the inventory they sell (rooms, pitches, bays, places in a pool) and what is left on each date.

GET /api/v1/inventory-types

List inventory types

Requires the event_types:read scope.

The kinds of thing the workspace sells by the night or by the day (rooms, pitches, bays, places in a pool), each with its active units. Types are shared by the whole workspace, like rooms, so every credential that may read event types lists all of them. Archived types are left out.

Responses

GET /api/v1/inventory-types/{id}

Get an inventory type

Requires the event_types:read scope.

One inventory type and its active units.

Parameters

Responses

GET /api/v1/stays/availability

What is left on each date of a stay

Requires the availability:read scope.

For an event type that sells nights or days, what is left on each date of a window of at most 62 days, per inventory a booker can choose: closed dates, dates a stay may not start or end on, a date's minimum stay, each date's price and the length-of-stay discounts. The same answer the booking page's date picker reads. Book a stay with POST /api/v1/bookings and stay. An event type of times answers 409 not_a_stay; its slots are GET /api/v1/availability/{slug}.

Parameters

Responses

POST /api/v1/bookings/{id}/stay-change

Change a stay's dates or inventory type

Requires the bookings:write scope.

Moves a stay: extend, shorten, shift, leave early, or change its inventory type. Periods the stay already held keep the price they were booked at and only new ones take today's rates, unless reprice. Send it first with preview (the default) to see the plan and the difference, then again with preview: false and that difference as expectedDifferenceCents to apply it: the inventory moves in one step or not at all (409 stay_unavailable naming the periods that no longer fit), the guest is emailed, reminders follow the new dates and booking.rescheduled fires with the old and new dates. A difference that moved since the preview is refused (409 stay_change_quote_changed).

Once checked in, a stay's arrival and type cannot change; a stay that checked out, one awaiting its payment, and one due to arrive already that never checked in cannot change at all.

Money stays on the stay. moneyAction is balance (the default when it costs more: the difference is owed) or none (the default when it costs less: any overpayment is left for staff to refund). Charging a saved card, sending a pay link and refunding are done from the dashboard.

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.

A stay that staff (or POST /api/v1/bookings/{id}/stay-change) moved carries its new dates in stay and the old ones in oldStay; oldStartTime/oldEndTime are the old check-in and check-out instants.

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

booking.checked_out

A stay checked out

Fires when staff, or a guest at a door screen, check out a stay that was checked in. The booking keeps its status; the payload adds checkedOutAt and checkedOutBy (staff or door), and carries the booking's stay. A second check-out of the same stay sends nothing. Not sent to a calendly-format subscriber: Calendly has no attendance events.

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.

ClaimError

The Error shape with the facts a checkout needs to act on: a refusal about a reservation made through your own checkout, or a requirement write refused for the same reason. Every field but message is present only when the refusal has it.

ClientBudgetError

A 429 from an OAuth client’s own budget, which every workspace the client is installed in shares. Names the budget that refused.

Contact

Error

The error shape used by every endpoint except the per-credential 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

InventoryType

A kind of thing an event type sells by the night or by the day. Workspace-shared, like rooms: every credential that may read event types lists all of them.

InventoryUnit

One unit of an inventory type: a room, a pitch, a bay, a run.

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

QuestionPatch

Any subset of the question’s fields. Only what you send changes.

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.

Stay

A booking of an event type that sells nights or days. The dates are authoritative for inventory and price; startTime/endTime on the booking are the check-in and check-out instants derived from them in the property zone.

StayAvailability

What is left on each date of a window, per inventory a booker can choose. The create step re-checks everything against the ledger, so a stale answer can only be refused, never oversold.

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.

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