Skip to main content
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 --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": "[email protected]",
      "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
​
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

​
Get a Booking

Retrieve a booking by its UID. 
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 --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 --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 --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 “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.

Build docs developers (and LLMs) love

Get started for freeTalk to us