Cal ID Scheduling API Reference

The Cal ID API is a REST API that lets you manage everything in Cal ID programmatically — event types, availability and schedules, bookable slots, bookings, teams, memberships, contacts, and webhooks. All requests and responses use JSON, and every endpoint is authenticated with an API key.

Base URL

All requests are made to https://api.cal.id.

Authentication

Cal ID authenticates requests with an API key sent as a Bearer token in the Authorization header.

Create an API key

In the Cal ID dashboard, go to Settings → Developer → API keys and create a key. Keys are prefixed with calid_. See Get your API key for the full walkthrough.

Send it with every request

Include the key in the Authorization header:

Authorization: Bearer calid_xxxxx

To manage a team’s resources (team event types, memberships, and schedules), use an API key belonging to a team owner or admin.

Your API key grants full access to your account. Keep it secret — never commit it to source control, embed it in client-side code, or share it in public links.

Sending a request body

POST and PATCH requests must carry a Content-Type: application/json header. Without it the request is rejected with 415 Unsupported Media Type before the body is parsed, even when the JSON you sent is perfectly valid.

curl -X POST https://api.cal.id/schedule/ \
  -H "Authorization: Bearer calid_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Weekday Working Hours"}'

Quickstart

Retrieve the authenticated user’s profile to confirm your key works:

curl https://api.cal.id/users/me \
  -H "Authorization: Bearer calid_xxxxx"

For the full path from a fresh API key to a confirmed booking, see the Quickstart guide.

Response format

Most responses are a JSON envelope built from success, data, message, and meta — but not every endpoint returns all four, and error responses from outside the API’s routing layer do not use the envelope at all. Write your client to read data defensively rather than assuming a fixed shape.

{
  "success": true,
  "data": [ ],
  "meta": {
    "pagination": { "page": 1, "limit": 10, "total": 34, "totalPages": 4 }
  },
  "message": "Request completed successfully"
}

{
  "success": true,
  "data": { },
  "message": "Request completed successfully"
}

{
  "success": true,
  "data": { }
}

{
  "success": false,
  "message": "A human-readable explanation of what went wrong",
  "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" }
}

{
  "message": "Route GET:/user/me not found",
  "error": "Not Found",
  "statusCode": 404
}

The four shapes observed in testing:

Shape	Seen on
`success` + `data` + `message`, no `meta`	`GET /users/me`, `GET /schedule/`, `GET /contacts/`
`success` + `data` + `meta.pagination` + `message`	`GET /event-types/`, `GET /booking/`, `GET /teams/`, `GET /webhook/`
`success` + `data` only — no `message`, no `meta`	`POST /slots/reserve`
`message` + `error` + `statusCode`, no `success`	Any unknown route, or a valid route called with the wrong HTTP method

The last shape is the one that breaks clients. When you typo a URL or use the wrong verb, the response has no success field at all, and error is a plain string ("Not Found") rather than the { code, message } object the API’s own errors use. Code that branches on if (!body.success) or reads body.error.code will throw instead of reporting a clean 404. Check the HTTP status code first, then the body.

The data field holds the resource or resources you requested. Read it rather than the top level.

data is not always an object or a list of objects with the shape you expect. GET /users/{userslug} returns data as an array, not a single user object — even though it looks up one user by slug. Index into it (data[0]) rather than reading fields off data directly.

Status codes

Code	Meaning	What to do
`200`	Success.	Read the resource from `data`.
`201`	Created. Returned by several create operations.	Treat `200` and `201` as equivalent success. Not every create returns `201` — do not test for `201` alone.
`400`	Bad request — the request is malformed. A missing or misnamed field, a wrong type, an out-of-range value, or an invalid enum.	Read `message` for the offending field and fix the request. Retrying unchanged will fail identically.
`401`	Unauthorized — missing, malformed, or invalid API key.	Check the `Authorization: Bearer calid_…` header.
`403`	Forbidden. Reserved for permission failures.	Not observed in testing with a valid key — a key that lacks access to a resource generally surfaces as `404` instead. Handle it, but do not expect it to be your common failure.
`404`	Not found. Two very different causes: the record you asked for does not exist, or the URL is not a route the API serves — including a real route called with the wrong HTTP method.	Verify the ID and the path and verb. The wrong-route form of `404` does not use the standard envelope (see Response format).
`415`	Unsupported Media Type — a `POST` or `PATCH` body was sent without `Content-Type: application/json`.	Add the header. The body is never parsed without it, so the error says nothing about your JSON.
`422`	Unprocessable entity — the request parsed but failed semantic validation, with `error.code: "VALIDATION_ERROR"`. Observed on `GET /slots/` when only `eventTypeSlug` is supplied.	Read `error.details[]`, which lists each failing `path` and `message`.
`429`	Too many requests — you have exhausted your rate-limit allowance.	Genuinely transient. Wait for `retryAfter` seconds, then back off exponentially. See Rate limits.
`500`	Internal error, with `error.code: "INTERNAL_ERROR"`. Despite the status class, this is usually caused by the request, not by an outage. The most common `500` is the domain error `no_available_users_found_error`, returned when you book a time that `GET /slots/` did not offer.	Read `message` before you retry. If it names a domain error such as `no_available_users_found_error`, the request is unbookable and every retry will fail identically — fix the input instead.

Do not treat 500 as a transient fault and retry it with backoff by default. On Cal ID, a 500 most often means the request asked for something the scheduling rules do not permit. Only 429 is reliably worth retrying.

See Error codes for every error.code value and the details shape that comes with each.

Pagination

Pagination is not uniform across the API. There are three different behaviours, and the default page size is not the same everywhere — so check this table before you write a paging loop.

Endpoint	Default `limit`	Paging parameters	Where the counts live
`GET /event-types/`	10	`page`, `limit` (max `100`)	`meta.pagination`
`GET /teams/` and other `/teams/*` list endpoints	10	`page`, `limit` (max `100`)	`meta.pagination`
`GET /booking/`	100	`page`, `limit`	`meta.pagination`
`GET /webhook/`	100	`page`, `limit`	`meta.pagination`
`GET /contacts/`, `GET /contacts/{id}/meetings`	10	`limit`, `offset` (max `limit` `100`)	`data.meta` — not `meta`
`GET /schedule/`, `GET /teams/{teamId}/schedules`	n/a — returns everything	none; `page` and `limit` are ignored	no `meta` at all

The standard envelope shape

/event-types/, /booking/, /teams/*, and /webhook/ page with page and limit and report progress in a top-level meta.pagination object.

curl "https://api.cal.id/booking/?page=1&limit=20" \
  -H "Authorization: Bearer calid_xxxxx"

{
  "success": true,
  "data": [ ],
  "meta": {
    "pagination": { "page": 1, "limit": 20, "total": 134, "totalPages": 7 }
  }
}

Contacts nest their pagination, with different key names

GET /contacts/ and GET /contacts/{id}/meetings put the records under data.rows and the counts under data.meta. The keys are not the ones used above — there is no total, page, or totalPages.

{
  "success": true,
  "data": {
    "rows": [ ],
    "meta": { "totalRowCount": 134, "hasMore": true, "limit": 10, "offset": 0 }
  },
  "message": "Request completed successfully"
}

Page these endpoints by advancing offset while data.meta.hasMore is true.

Schedules are not paginated at all

GET /schedule/ and GET /teams/{teamId}/schedules return the complete list in data and carry no meta object. They accept page and limit in the query string without complaint, but ignore them — passing ?limit=1 still returns every schedule. Do not write a paging loop against these endpoints; it will either never terminate or silently re-read the same full list.

Limit ceilings

For /event-types/, /contacts/, and /teams/*, the maximum limit is 100. Asking for more is rejected:

{
  "success": false,
  "message": "querystring/limit must be <= 100",
  "error": { "code": "FST_ERR_VALIDATION" }
}

The 100 ceiling is confirmed for /event-types/, /contacts/, and /teams/*. It was not tested on /booking/ or /webhook/, which already default to 100 — assume the same ceiling until you have verified otherwise.

Never rely on a default page size. GET /event-types/ returning 10 records does not mean you have 10 event types; it means you did not pass limit. Always set limit explicitly and page until the results are exhausted.

Dates and times

Almost every endpoint sends and receives timestamps as ISO-8601 strings — 2026-09-08T03:30:00.000Z. GET /availability/ is the exception. It returns RFC-1123 date strings instead:

"Tue, 08 Sep 2026 03:30:00 GMT"

A parser that assumes ISO-8601 everywhere will fail on GET /availability/ responses. Parse that endpoint’s dates as RFC-1123, or normalise them before they reach the rest of your code. Which other endpoints, if any, share this format has not been established — treat ISO-8601 as the rule and check /availability/ output explicitly.

GET /availability/ also requires the dateFrom query parameter. Calling it without one returns 400, not an unbounded list:

curl -G https://api.cal.id/availability/ \
  -H "Authorization: Bearer calid_xxxxx" \
  --data-urlencode "dateFrom=2026-09-08" \
  --data-urlencode "dateTo=2026-09-15"

Filtering and sorting

Most list endpoints accept filters and sort keys as query parameters. For example, List bookings supports filtering by status, eventTypeIds, attendeeEmail, and date ranges (afterStartDate, beforeEndDate, afterCreatedDate, …), plus sorting with sortStart, sortCreated, and sortUpdated. See each endpoint’s Query Parameters for the full set.

GET /booking/ defaults to status=upcoming. With no status parameter you will not see past bookings, and there is no “all” value — page each bucket (upcoming, past, cancelled, unconfirmed, recurring) separately.

Developer guides and references

Quickstart

From a fresh API key to a confirmed booking in five requests.

Error codes

Every error.code the API returns, and what to do about each.

Get your API key

Create and manage the keys that authenticate your requests.

Find your Event Type ID

Locate the IDs you’ll pass to booking and event-type endpoints.

Webhooks

Subscribe to booking and meeting events in real time.

Integration overview

How the API is structured, from servers to authentication.

Rate limits

Stay under your allowance and recover cleanly from a 429.

Guides

Task-shaped recipes for bookings, slots, schedules, teams, and contacts.

Get started

Endpoints

Cal ID Scheduling API Reference

Base URL

Authentication

Sending a request body

Quickstart

Response format

Status codes

The standard envelope shape

Schedules are not paginated at all

Limit ceilings

Dates and times

Filtering and sorting

Developer guides and references

Quickstart

Error codes

Get your API key

Find your Event Type ID

Webhooks

Integration overview

Rate limits

Guides

Base URL

​Authentication

​Sending a request body

​Quickstart

​Response format

​Status codes

​Pagination

​The standard envelope shape

​Contacts nest their pagination, with different key names

​Schedules are not paginated at all

​Limit ceilings

​Dates and times

​Filtering and sorting

​Developer guides and references

Quickstart

Error codes

Get your API key

Find your Event Type ID

Webhooks

Integration overview

Rate limits

Guides

Authentication

Sending a request body

Quickstart

Response format

Status codes

Pagination

The standard envelope shape

Contacts nest their pagination, with different key names

Schedules are not paginated at all

Limit ceilings

Dates and times

Filtering and sorting

Developer guides and references