Bookings

The bookings object holds all the necessary information regarding the booking of an event.

Booking Object

AttributeDescription
id

integer

The ID of the booking, generated automatically
uid

string

Unique identifier for the booking
idempotencyKey

string

Optional UID based on slot start/end time & email to prevent duplicates
user

User Object

The user associated with the booking. Please check the Users endpoint for details on the User Object
userId

integer

The ID of the user associated with the booking
userPrimaryEmail

email

User's email at the time of booking
references

BookingReference Object[]

References associated with the booking. Please check the Booking Reference endpoint for details on the BookingReference Object
eventType

EventType Object

The event type associated with the booking. Please check the Event Type endpoint for details on the EventType Object
eventTypeId

integer

The ID of the event type associated with the booking
title

string

The title of the booking
description

string

The description of the booking
responses

json

Responses for the booking questions
startTime

DateTime

The start time of the booking
endTime

DateTime

The end time of the booking
attendees

Attendee Object[]

List of attendees for the booking. Please check the Attendee endpoint for details on the Attendee Object
createdAt

DateTime

The creation time of the booking
updatedAt

DateTime

The last update time of the booking
status

enum

The current status of the booking. Please check the Booking Status Enums for details on the Booking Status constants
paid

boolean

Whether the booking is paid
payment

Payment Object[]

List of payments for the booking. Please check the Payment endpoint for details on the Payment Object
destinationCalendar

DestinationCalendar Object

The destination calendar associated with the booking. Please check the Destination Calendar endpoint for details on the Destination Calendar Object
destinationCalendarId

integer

The ID of the destination calendar associated with the booking
cancellationReason

string

Reason for cancellation
rejectionReason

string

Reason for rejection
dynamicEventSlugRef

string

Reference for dynamic event slug
dynamicGroupSlugRef

string

Reference for dynamic group slug
rescheduled

boolean

Whether the booking is rescheduled
fromReschedule

string

Source of reschedule
recurringEventId

string

ID of the recurring event
smsReminderNumber

string

SMS reminder number
workflowReminders

WorkflowReminder Object[]

List of workflow reminders for the booking.
seatsReferences

BookingSeat Object[]

References for booking seats
metadata

json

Metadata associated with the booking
isRecorded

boolean

Whether the booking is recorded
iCalUID

string

iCal UID for the booking
iCalSequence

integer

iCal sequence for the booking
instantMeetingToken

InstantMeetingToken Object

Token for instant meeting
rating

integer

Rating for the booking
ratingFeedback

string

Feedback for the rating
noShowHost

boolean

Whether the host was a no-show
scheduledTriggers

WebhookScheduledTriggers Object[]

Scheduled triggers for the booking

Booking Status Constants

Enum ConstantDescription
CANCELLED

string

If the booking is cancelled
ACCEPTED

string

If the booking is accepted or confirmed
REJECTED

string

If the booking request is rejected
PENDING

string

If the booking it yet to be confirmed or rejected
AWAITING_HOST

string

If the booking is awaiting host

Location Object

The location object defines the meeting/event location and is defined within the responses object in the Booking Object. The responses object contains the information filled in by the user to the booking questions.

You can simply copy the object in the description below and paste it inside the responses object of the booking payload. An example of this for zoom as booking location would be:

    {
        ...,
        "responses": {
            ...,
            "location": {
                "value": "integrations:zoom",
                "optionValue": ""
            },
        }
        ...,
    }

Depending on the location selected, the location object can be one of the following:

Location object forDescription
HostPhone

json

{'value': 'userPhone', 'optionValue': ''}
AttendeePhone

json

{'value': 'phone', 'optionValue': '+1 234 567 890'}
Link

json

{'value': 'link', 'optionValue': ''}
HostInPersonAddress

json

{'value': 'inPerson', 'optionValue': ''}
AttendeeInPersonAddress

json

{'value': 'attendeeInPerson', 'optionValue': 'Acme HQ'}
CalVideo

json

{'value': 'integrations:daily', 'optionValue': ''}
GoogleMeet

json

{'value': 'integrations:google:meet', 'optionValue': ''}
Zoom

json

{'value': 'integrations:zoom', 'optionValue': ''}
AroundVideo

json

{'value': 'integrations:around_video', 'optionValue': ''}
CampfireVideo

json

{'value': 'integrations:campfire_video', 'optionValue': ''}
DemodeskVideo

json

{'value': 'integrations:demodesk_video', 'optionValue': ''}
DiscordVideo

json

{'value': 'integrations:discord_video', 'optionValue': ''}
FacetimeVideo

json

{'value': 'integrations:facetime_video', 'optionValue': ''}
MirotalkVideo

json

{'value': 'integrations:mirotalk_video', 'optionValue': ''}
WherebyVideo

json

{'value': 'integrations:whereby_video', 'optionValue': ''}
Huddle

json

{'value': 'integrations:huddle01', 'optionValue': ''}

Example Booking Object

{
    "id": 789,
    "uid": "unique-booking-identifier",
    "idempotencyKey": "unique-idempotency-key",
    "user": [User Object],
    "userId": 456,
    "userPrimaryEmail": "[email protected]",
    "references": [BookingReference Object[]],
    "eventType": [EventType Object],
    "eventTypeId": 101,
    "title": "Business Meeting",
    "description": "Quarterly business review meeting",
    "responses": {
        "name": "Ilaria",
        "email": "[email protected]",
        "guests": [],
        "location": [Location Object]
    },
    "startTime": "2024-07-20T10:00:00Z",
    "endTime": "2024-07-20T11:00:00Z",
    "attendees": [Attendee Object[]],
    "createdAt": "2024-07-19T08:00:00Z",
    "updatedAt": "2024-07-19T09:00:00Z",
    "status": "confirmed",
    "paid": true,
    "payment": [Payment Object[]],
    "destinationCalendar": [DestinationCalendar Object],
    "destinationCalendarId": 202,
    "cancellationReason": "Client requested reschedule",
    "rejectionReason": "Not applicable",
    "dynamicEventSlugRef": "event-slug-reference",
    "dynamicGroupSlugRef": "group-slug-reference",
    "rescheduled": false,
    "fromReschedule": "Not applicable",
    "recurringEventId": "recurring-event-123",
    "smsReminderNumber": "+1234567890",
    "workflowReminders": [WorkflowReminder Object[]],
    "seatsReferences": [BookingSeat Object[]],
    "metadata": {
        "metaKey1": "metaValue1",
    },
    "isRecorded": true,
    "iCalUID": "ical-uid-123456",
    "iCalSequence": 1,
    "instantMeetingToken": [InstantMeetingToken Object],
    "rating": 5,
    "ratingFeedback": "Excellent meeting",
    "noShowHost": false,
    "scheduledTriggers": [WebhookScheduledTriggers Object[]]
}

These routes allow you to CRUD bookings within Cal.com

Admin access

This endpoint supports System Wide Admin access, as well as Organization Wide Admin access.

As an Organization Admin, you can now query bookings for your Organization members for GET, POST, PATCH, and DELETE

Pagination

We have added pagination to this endpoint to handle large responses. You can now use the take and page query parameters to get the specific batch of bookings you need.

  • take: The maximum number of bookings you want in a batch.
  • page: The page number to retrieve the bookings from, based on the total number of bookings divided by take.

Example:

If there are 100 total bookings and you set take to 25, there will be 4 pages of bookings. To get bookings 26-50, set page to 2.

Usage:

  • take: Maximum number of bookings per batch (e.g., 25)
  • page: Page number to retrieve (e.g., 2)

This way, you can easily navigate through large sets of bookings by specifying how many bookings you want per batch and which batch to retrieve.

Note: Pagination is optional, in the absence of take and page, the response will contain all bookings.

Find all bookings

This API call lists all the bookings of the user making the call.

GET

/bookings

Please note that the use of userId for filtering the bookings in the GET request is an ADMIN only call. This will not yeild the filtering for non-admin API calls

Create a new booking

This API call is used to create a new booking.

POST

/bookings

Find a booking

This API call is used to retrieve a specific booking of the user, identified by the booking id.

GET

/bookings/{id}

Edit an existing booking

This API call is used to edit a specific booking of the user, identified by the booking id. Currently, you can only change the title, start, end, status and description of the booking.

PATCH

/bookings/{id}

Cancel an existing booking

This API call is used to cancel a specific booking of the user, identified by the booking id.

DELETE

/bookings/{id}/cancel

To reschedule a booking, simply cancel the original booking using the Cancel Booking API call, and then proceed to make a new booking using the Create Booking API call.

Was this page helpful?