Bookings

Manage bookings through the Cal.com API

The Bookings API allows you to create, retrieve, update, and cancel bookings programmatically.

API Version

All booking endpoints require the cal-api-version header:

cal-api-version: 2024-08-13

Authentication

Booking endpoints support multiple authentication methods:

• API Key: Pass via Authorization: Bearer <api-key> header
• Access Token: OAuth access token
• Client Credentials: For public bookings, use x-cal-client-id and x-cal-secret-key headers
• Optional Auth: Some endpoints allow unauthenticated access

Create a Booking

Create a new booking, recurring booking, or instant booking.

cURL

curl --request POST \
  --url https://api.cal.com/v2/bookings \
  --header 'cal-api-version: 2024-08-13' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2024-12-10T09:00:00Z",
    "eventTypeId": 123,
    "attendee": {
      "name": "John Doe",
      "email": "[e-mail]",
      "timeZone": "America/New_York"
    },
    "meetingUrl": "https://meet.example.com/meeting-123"
  }'

Request Body

eventTypeId · number

The ID of the event type to book

start · string · required

Start time in UTC ISO 8601 format (e.g., “2024-12-10T09:00:00Z”)

attendee · object · required

Attendee information

Show child attributes

name · string · required

Attendee’s full name

email · string · required

Attendee’s email address

timeZone · string · required

Attendee’s timezone (e.g., “America/New_York”)

phoneNumber · string

Phone number in international format (required if SMS reminders are enabled)

meetingUrl · string

Custom meeting URL (optional)

instant · boolean

Set to true for instant meetings (team event types only)

eventTypeSlug · string

Alternative to eventTypeId: provide slug with username/teamSlug

username · string

Username for individual user bookings (used with eventTypeSlug)

teamSlug · string

Team slug for team bookings (used with eventTypeSlug)

Response

status · string

Status of the response (“success” or “error”)

data · object

Booking details

Show child attributes

id · number

Unique booking ID

uid · string

Unique booking identifier

title · string

Booking title

start · string

Start time in ISO 8601 format

end · string

End time in ISO 8601 format

status · string

Booking status (“accepted”, “pending”, “cancelled”)

attendees · array

Array of attendee objects

Get a Booking

Retrieve a booking by its UID.

cURL

curl --request GET \
  --url https://api.cal.com/v2/bookings/{bookingUid} \
  --header 'cal-api-version: 2024-08-13'

Path Parameters

bookingUid · string · required

The unique identifier of the booking. Can be:

• UID of a normal booking
• UID of one recurring booking recurrence
• UID of recurring booking (returns all recurrences)

Get All Bookings

List all bookings for the authenticated user.

cURL

curl --request GET \
  --url 'https://api.cal.com/v2/bookings?status=upcoming&limit=10' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'cal-api-version: 2024-08-13'

Query Parameters

status · string

Filter by booking status: “upcoming”, “past”, “cancelled”

limit · number

Number of bookings to return (default: 10)

cursor · string

Pagination cursor for next page

Reschedule a Booking

Change the time of an existing booking.

cURL

curl --request POST \
  --url https://api.cal.com/v2/bookings/{bookingUid}/reschedule \
  --header 'cal-api-version: 2024-08-13' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2024-12-11T10:00:00Z",
    "reschedulingReason": "Conflict with another meeting"
  }'

Request Body

start · string · required

New start time in UTC ISO 8601 format

reschedulingReason · string

Reason for rescheduling

Cancel a Booking

Cancel an existing booking.

cURL

curl --request POST \
  --url https://api.cal.com/v2/bookings/{bookingUid}/cancel \
  --header 'cal-api-version: 2024-08-13' \
  --header 'Content-Type: application/json' \
  --data '{
    "cancellationReason": "Unable to attend"
  }'

Request Body

cancellationReason · string

Reason for cancellation

seatUid · string

For seated bookings: specific seat to cancel

Additional Endpoints

Confirm a Booking

Confirm a pending booking (requires authentication as booking owner).

POST /v2/bookings/{bookingUid}/confirm

Decline a Booking

Decline a pending booking (requires authentication as booking owner).

POST /v2/bookings/{bookingUid}/decline

Mark Absent

Mark an attendee as absent from a booking.

POST /v2/bookings/{bookingUid}/mark-absent

Reassign Booking

Reassign a round-robin booking to a different host.

POST /v2/bookings/{bookingUid}/reassign
POST /v2/bookings/{bookingUid}/reassign/{userId}

Get Calendar Links

Get “Add to Calendar” links for a booking.

GET /v2/bookings/{bookingUid}/calendar-links

Get Recordings

Fetch Cal Video recordings for a booking (requires proper authorization).

GET /v2/bookings/{bookingUid}/recordings

Get Transcripts

Get Cal Video transcript download links (valid for 1 hour).

GET /v2/bookings/{bookingUid}/transcripts

Notes

• The start time must be in UTC. For example, if a meeting should start at 11:00 in Rome (GMT+2), pass 09:00 UTC.
• For seated bookings with hidden attendees, authentication as event owner/host/team admin/org admin is required to view attendees.
• Recurring bookings are created by passing an event type ID that is configured as recurring.
• For SMS reminder workflows, include the attendee’s phoneNumber in international format.