Bookings

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

Booking Object

Booking Status Constants

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:

Example Booking Object

{
    "id": 789,
    "uid": "unique-booking-identifier",
    "idempotencyKey": "unique-idempotency-key",
    "user": [User Object],
    "userId": 456,
    "userPrimaryEmail": "john.doe@example.com",
    "references": [BookingReference Object[]],
    "eventType": [EventType Object],
    "eventTypeId": 101,
    "title": "Business Meeting",
    "description": "Quarterly business review meeting",
    "responses": {
        "name": "Ilaria",
        "email": "igrassi@learnn.com",
        "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.

Create a new booking

This API call is used to create a new booking.

Find a booking

This API call is used to retrieve a specific booking of the user, identified by the booking 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.

Cancel an existing booking

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