Reserve a slot before booking

When a booker picks a time, you often need a few moments for them to fill out a form before the booking is final. To avoid two people grabbing the same slot, use a hold-then-confirm pattern: reserve the slot to place a temporary hold, let the booker complete checkout, then confirm by creating the booking. If they never finish, the hold expires on its own. All requests use the base URL https://api.cal.id and are authenticated with a Bearer token.

Before you begin, make sure you have:

An API key to authenticate your requests.
The event type’s ID you want to book.

Reserve the slot

Call POST /slots/reserve with the eventTypeId (integer) and the slotStart (ISO) you want to hold. Optionally pass slotDuration (minutes) and reservationDuration (how long to hold the slot, in minutes).

curl -X POST https://api.cal.id/slots/reserve \
  -H "Authorization: Bearer calid_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "eventTypeId": 123,
    "slotStart": "2026-05-02T10:00:00.000Z",
    "reservationDuration": 10
  }'

async function reserveSlot() {
  const res = await fetch("https://api.cal.id/slots/reserve", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CALID_KEY}`,
      // Mandatory on POST/PATCH — without it the API returns 415.
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      eventTypeId: 123,
      slotStart: "2026-05-02T10:00:00.000Z",
      reservationDuration: 10,
    }),
  });

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

  // The hold's identifier is reservationUid — not uid.
  return body.data.reservationUid;
}

reserveSlot().then((reservationUid) => console.log(reservationUid));

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]

response = requests.post(
    "https://api.cal.id/slots/reserve",
    headers={
        "Authorization": f"Bearer {CALID_KEY}",
        # Mandatory on POST/PATCH — without it the API returns 415.
        "Content-Type": "application/json",
    },
    json={
        "eventTypeId": 123,
        "slotStart": "2026-05-02T10:00:00.000Z",
        "reservationDuration": 10,
    },
)
response.raise_for_status()

# The hold's identifier is reservationUid — not uid.
reservation_uid = response.json()["data"]["reservationUid"]
print(reservation_uid)

The reservation is returned in data as reservationUid — note the field is not called uid. Keep it; you need it to release the hold early. The hold lasts 5 minutes unless you pass reservationDuration (in minutes).

{
  "success": true,
  "data": {
    "reservationUid": "1dbf6190-6ca3-4da2-8871-33cd15980b35",
    "eventTypeId": 123,
    "slotStart": "2026-05-02T10:00:00.000Z",
    "reservationDuration": 10
  },
  "message": "Slot reserved successfully.",
  "meta": {}
}

Confirm the booking

While the hold is active, let the booker finish checkout, then create the booking as usual with POST /booking/ (its body includes eventTypeId, start, end, and responses with name and email). See Create a booking for the full flow.If the booking isn’t confirmed within reservationDuration minutes, the hold expires automatically and the slot becomes available to others again.

Release the hold

If the booker cancels or backs out before confirming, release the hold early instead of waiting for it to expire. Call DELETE /slots/\{reservationUid\} with the reservationUid from Step 1.

curl -X DELETE https://api.cal.id/slots/1dbf6190-6ca3-4da2-8871-33cd15980b35 \
  -H "Authorization: Bearer calid_xxxxx"

const reservationUid = "1dbf6190-6ca3-4da2-8871-33cd15980b35";

async function releaseHold() {
  const res = await fetch(`https://api.cal.id/slots/${reservationUid}`, {
    method: "DELETE",
    headers: { Authorization: `Bearer ${process.env.CALID_KEY}` },
  });

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

  console.log("Hold released");
}

releaseHold();

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]
reservation_uid = "1dbf6190-6ca3-4da2-8871-33cd15980b35"

response = requests.delete(
    f"https://api.cal.id/slots/{reservation_uid}",
    headers={"Authorization": f"Bearer {CALID_KEY}"},
)
response.raise_for_status()

print("Hold released")

Slot reservation reference

Reserve a slot — full endpoint reference

A successful reservation does not guarantee the booking will succeed. POST /slots/reserve does not re-check availability — reserving a time that GET /slots/ never offered returns 200, and the later POST /booking/ then fails with no_available_users_found_error. Always reserve a slot that came back from GET /slots/.

Get started

Guides

Reserve a slot before booking

Slot reservation reference

​Slot reservation reference

Slot reservation reference