The bookings object holds all the necessary information regarding the booking of an event.
Booking Object
Attribute | Description |
---|---|
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 | 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 Constant | Description |
---|---|
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 for | Description |
---|---|
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 bytake
.
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
andpage
, the response will contain all bookings.
Find all bookings
This API call lists all the bookings of the user making the call.
/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.
/bookings
Find a booking
This API call is used to retrieve a specific booking of the user, identified by the booking id.
/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.
/bookings/{id}
Cancel an existing booking
This API call is used to cancel a specific booking of the user, identified by the booking id.
/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.