Introduction

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.

Quickstart

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

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

Response format

Every response is a JSON envelope with a consistent shape.

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

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

The data field holds the resource or resources you requested. On list endpoints, meta carries pagination and contextual information.

Status codes

Code	Meaning
`200`	Success
`400`	Bad request — check your parameters
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — your key lacks permission for this resource
`500`	Something went wrong on Cal ID’s side

Pagination

List endpoints are paginated with page and limit query parameters, and return the current page details in meta.pagination.

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 }
  }
}

A few endpoints (such as Contacts) page with limit and offset instead of page. Check each endpoint’s parameters.

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.

Next steps

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.

Get started

Endpoints

Base URL

Authentication

Quickstart

Response format

Status codes

Filtering and sorting

Next steps

Get your API key

Find your Event Type ID

Webhooks

Integration overview

Base URL

​Authentication

​Quickstart

​Response format

​Status codes

​Pagination

​Filtering and sorting

​Next steps

Get your API key

Find your Event Type ID

Webhooks

Integration overview

Authentication

Quickstart

Response format

Status codes

Pagination

Filtering and sorting

Next steps