Cal ID API Quickstart

This page takes you from nothing to a real booking on your own account, in five requests. Every call runs against https://api.cal.id and is authenticated with a bearer token. Work through it in order — each step produces a value the next one needs, and the last step will fail if you skip ahead and invent a time rather than using one the API gave you.

You need a Cal ID account with at least one event type. If you have none, create one in the dashboard first — this guide reads an existing event type rather than creating one.

Get an API key

In the Cal ID dashboard, go to Settings → Developer → API Keys and create a key. Keys are prefixed with calid_ and are shown once, so copy it somewhere safe immediately.See Get your API key for the full walkthrough, including expiry options.

Your API key grants full access to your account. Never commit it to source control or put it in client-side code. Keep it in an environment variable:

export CALID_KEY="calid_xxxxx"

Confirm the key works

Call GET /users/me. It is the cheapest way to prove your key and header are correct before you debug anything else.

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

async function whoAmI() {
  const res = await fetch("https://api.cal.id/users/me", {
    headers: { Authorization: `Bearer ${process.env.CALID_KEY}` },
  });

  const body = await res.json();

  if (!res.ok) {
    // 401 means the header is wrong, or the key is invalid or expired.
    throw new Error(`HTTP ${res.status}: ${body.message ?? "request failed"}`);
  }

  // GET /users/me returns data as an object.
  return body.data;
}

whoAmI().then((user) => console.log(user.username, user.timeZone));

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]

response = requests.get(
    "https://api.cal.id/users/me",
    headers={"Authorization": f"Bearer {CALID_KEY}"},
)

if response.status_code == 401:
    # The header is wrong, or the key is invalid or expired.
    raise SystemExit("Unauthorized — check your API key")

response.raise_for_status()

# GET /users/me returns data as an object.
user = response.json()["data"]
print(user["username"], user["timeZone"])

A working key returns your profile inside data:

{
  "success": true,
  "data": {
    "id": 1234,
    "username": "jane-doe",
    "email": "jane@example.com",
    "timeZone": "Asia/Kolkata"
  },
  "message": "Request completed successfully"
}

If you get 401 with error.code: "UNAUTHORIZED", the header is wrong or the key is invalid or expired. If you get a 404 whose body has no success field, you have mistyped the URL — that response comes from the router, not the API. See Error codes.

GET /users/me returns data as an object. Its sibling GET /users/{userslug} returns data as an array — read that one as data[0].

Find an event type ID

Every booking is made against an event type. List yours and pick one.

curl -G https://api.cal.id/event-types/ \
  -H "Authorization: Bearer $CALID_KEY" \
  --data-urlencode "limit=100"

async function listEventTypes() {
  // Always pass limit explicitly: the default is 10, the maximum is 100.
  const params = new URLSearchParams({ limit: "100" });

  const res = await fetch(`https://api.cal.id/event-types/?${params}`, {
    headers: { Authorization: `Bearer ${process.env.CALID_KEY}` },
  });

  const body = await res.json();
  if (!res.ok) throw new Error(body.message ?? `HTTP ${res.status}`);

  // Records in data, paging state in meta.pagination.
  return { eventTypes: body.data, pagination: body.meta.pagination };
}

listEventTypes().then(({ eventTypes, pagination }) => {
  for (const e of eventTypes) console.log(e.id, e.title, e.length);
  console.log(`${eventTypes.length} of ${pagination.total}`);
});

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]

# Always pass limit explicitly: the default is 10, the maximum is 100.
response = requests.get(
    "https://api.cal.id/event-types/",
    headers={"Authorization": f"Bearer {CALID_KEY}"},
    params={"limit": 100},
)
response.raise_for_status()

body = response.json()
for event_type in body["data"]:
    print(event_type["id"], event_type["title"], event_type["length"])

# Paging state lives in meta.pagination.
print(f"{len(body['data'])} of {body['meta']['pagination']['total']}")

GET /event-types/ returns 10 records by default. If you omit limit, an account with 40 event types silently looks like it has 10, and the one you were after may simply not be in the response. Always pass limit explicitly. The maximum is 100; ?limit=1000 is rejected with 400 — querystring/limit must be <= 100.

The list arrives in data, with paging state in meta.pagination. Note the id of the event type you want to book, and its length in minutes — you need both.

{
  "success": true,
  "data": [
    { "id": 12345, "title": "30 Minute Meeting", "slug": "30min", "length": 30 }
  ],
  "meta": {
    "pagination": { "page": 1, "limit": 100, "total": 1, "totalPages": 1 }
  },
  "message": "Request completed successfully"
}

You can also read the ID straight from the dashboard URL while editing an event — see Find your Event Type ID.

Fetch real bookable slots

Ask the API which times are actually available. Do not compute this yourself: availability is the product of schedules, buffers, minimum notice, booking limits, connected-calendar busy times, and timezone rules, and a reimplementation will not match.

curl -G https://api.cal.id/slots/ \
  -H "Authorization: Bearer $CALID_KEY" \
  --data-urlencode "eventTypeId=12345" \
  --data-urlencode "start=2026-09-08T00:00:00.000Z" \
  --data-urlencode "end=2026-09-09T00:00:00.000Z" \
  --data-urlencode "timeZone=Asia/Kolkata"

async function getSlots() {
  const params = new URLSearchParams({
    // On /slots/ the event type ID is a string; on /booking/ it is an integer.
    eventTypeId: "12345",
    start: "2026-09-08T00:00:00.000Z",
    end: "2026-09-09T00:00:00.000Z",
    timeZone: "Asia/Kolkata",
  });

  const res = await fetch(`https://api.cal.id/slots/?${params}`, {
    headers: { Authorization: `Bearer ${process.env.CALID_KEY}` },
  });

  const body = await res.json();
  if (!res.ok) throw new Error(body.message ?? `HTTP ${res.status}`);

  // Slots nest as data.slots["YYYY-MM-DD"][].time — not data[0].
  return body.data.slots;
}

getSlots().then((slots) => {
  const day = slots["2026-09-08"] ?? [];
  if (day.length === 0) throw new Error("Nothing bookable in that window");
  console.log(day[0].time);
});

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]

response = requests.get(
    "https://api.cal.id/slots/",
    headers={"Authorization": f"Bearer {CALID_KEY}"},
    params={
        # On /slots/ the event type ID is a string; on /booking/ it is an int.
        "eventTypeId": "12345",
        "start": "2026-09-08T00:00:00.000Z",
        "end": "2026-09-09T00:00:00.000Z",
        "timeZone": "Asia/Kolkata",
    },
)
response.raise_for_status()

# Slots nest as data.slots["YYYY-MM-DD"][].time — not data[0].
slots = response.json()["data"]["slots"]
day = slots.get("2026-09-08", [])
if not day:
    raise SystemExit("Nothing bookable in that window")

print(day[0]["time"])

On GET /slots/, eventTypeId is a string, not an integer. POST /booking/ in the next step takes the same ID as an integer. If you build requests from a typed client or a schema, you must convert between the two — sending the wrong type is rejected with 400.

The response nests slots two levels deep: data.slots is an object keyed by date ("YYYY-MM-DD"), and each value is an array of slot objects whose bookable time is in time.

{
  "success": true,
  "data": {
    "slots": {
      "2026-09-08": [
        { "time": "2026-09-08T03:30:00.000Z" },
        { "time": "2026-09-08T04:00:00.000Z" }
      ]
    }
  },
  "message": "Request completed successfully"
}

Read your chosen time as data.slots["2026-09-08"][0].time — not data[0] and not data.slots[0].If the date key you expected is missing, or its array is empty, there is genuinely nothing bookable in that window. Widen start/end or check the event type’s schedule before moving on.

Create the booking

Post the slot you just read. start, end, and responses (with at least name and email) are required, and end is start plus the event type’s length in minutes.

curl -X POST https://api.cal.id/booking/ \
  -H "Authorization: Bearer $CALID_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventTypeId": 12345,
    "start": "2026-09-08T03:30:00.000Z",
    "end": "2026-09-08T04:00:00.000Z",
    "timeZone": "Asia/Kolkata",
    "responses": {
      "name": "Jane Doe",
      "email": "jane@example.com"
    }
  }'

async function createBooking() {
  const res = await fetch("https://api.cal.id/booking/", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CALID_KEY}`,
      // Mandatory — omit it and the body is never parsed.
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      // Integer here, string on /slots/.
      eventTypeId: 12345,
      // start and end — never startTime/endTime.
      start: "2026-09-08T03:30:00.000Z",
      end: "2026-09-08T04:00:00.000Z",
      timeZone: "Asia/Kolkata",
      responses: {
        name: "Jane Doe",
        email: "jane@example.com",
      },
    }),
  });

  const body = await res.json();

  if (!res.ok) {
    if (body.message === "no_available_users_found_error") {
      // Deterministic — do not retry. Re-read GET /slots/ instead.
      throw new Error("That start time is not bookable. Re-fetch slots.");
    }
    throw new Error(`HTTP ${res.status}: ${body.message ?? "request failed"}`);
  }

  return body.data;
}

createBooking().then((booking) => console.log(booking.uid));

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]

response = requests.post(
    "https://api.cal.id/booking/",
    headers={
        "Authorization": f"Bearer {CALID_KEY}",
        # Mandatory — omit it and the body is never parsed.
        "Content-Type": "application/json",
    },
    json={
        # Integer here, string on /slots/.
        "eventTypeId": 12345,
        # start and end — never startTime/endTime.
        "start": "2026-09-08T03:30:00.000Z",
        "end": "2026-09-08T04:00:00.000Z",
        "timeZone": "Asia/Kolkata",
        "responses": {
            "name": "Jane Doe",
            "email": "jane@example.com",
        },
    },
)

if not response.ok:
    body = response.json()
    if body.get("message") == "no_available_users_found_error":
        # Deterministic — do not retry. Re-read GET /slots/ instead.
        raise SystemExit("That start time is not bookable. Re-fetch slots.")
    response.raise_for_status()

print(response.json()["data"]["uid"])

Content-Type: application/json is mandatory. Omit it and the body is never parsed — you get 400 — body must be object even though the JSON is perfectly valid.

The created booking comes back in data, including its uid.

{
  "success": true,
  "data": {
    "uid": "abc123XYZ",
    "start": "2026-09-08T03:30:00.000Z",
    "end": "2026-09-08T04:00:00.000Z"
  },
  "message": "Booking created successfully."
}

If the booking fails with a 500

The most common failure in this flow is:

{
  "success": false,
  "message": "no_available_users_found_error",
  "error": { "code": "INTERNAL_ERROR" }
}

Despite the 500, this is not a Cal ID outage — it means the start you sent is not a time the scheduling rules will accept. Almost always the cause is that start did not come from Step 4.

Do not retry a no_available_users_found_error with backoff. It is deterministic: every retry with the same start fails identically. Go back to GET /slots/ and use a time it actually returned.

Two things that look fine but are not:

A time that is obviously free on your calendar. Availability is not the same as “not busy” — buffers, minimum notice, and booking limits all remove otherwise-empty times.
A time echoed back from a booking object. Booking responses use startTime and endTime; the request body uses start and end. You cannot round-trip a booking object straight back into POST /booking/.

What you just learned

Behaviour	Why it matters
`GET /event-types/` defaults to `limit=10`	Missing records look like deleted records.
`eventTypeId` is a string on `/slots/`, an integer on `/booking/`	Typed clients need an explicit conversion.
Slots nest as `data.slots["YYYY-MM-DD"][].time`	`data[0]` returns `undefined`, not an error.
`Content-Type: application/json` is mandatory on `POST`	Omitting it produces a `400` that blames your body.
`start` must be a time `/slots/` returned	Otherwise you get a `500` that no retry will fix.

Go deeper with the API

API integration

The conventions that apply across every endpoint — envelopes, pagination, and the traps.

Error codes

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

Reserve a slot before booking

Hold a time while the booker completes checkout, so nobody else takes it.

Reschedule and cancel

Move or cancel a booking you created.

Webhooks

Get booking events pushed to you instead of polling.

API Reference

Every endpoint, with schemas and a live “Try it” playground.

Get started

Guides

Cal ID API Quickstart

If the booking fails with a 500

What you just learned

Go deeper with the API

API integration

Error codes

Reserve a slot before booking

Reschedule and cancel

Webhooks

API Reference

​If the booking fails with a 500

​What you just learned

​Go deeper with the API

API integration

Error codes

Reserve a slot before booking

Reschedule and cancel

Webhooks

API Reference

If the booking fails with a 500

What you just learned

Go deeper with the API