Get all bookings

curl --request GET \
  --url https://api.cal.com/v2/bookings \
  --header 'Authorization: <authorization>' \
  --header 'cal-api-version: <cal-api-version>'

{
  "status": "success",
  "data": [
    {
      "id": 123,
      "uid": "booking_uid_123",
      "title": "Consultation",
      "description": "Learn how to integrate scheduling into marketplace.",
      "hosts": [
        {
          "id": 1,
          "name": "Jane Doe",
          "email": "[email protected]",
          "username": "jane100",
          "timeZone": "America/Los_Angeles"
        }
      ],
      "status": "accepted",
      "start": "2024-08-13T15:30:00Z",
      "end": "2024-08-13T16:30:00Z",
      "duration": 60,
      "eventTypeId": 50,
      "eventType": {
        "id": 1,
        "slug": "some-event"
      },
      "location": "https://example.com/meeting",
      "absentHost": true,
      "createdAt": "2024-08-13T15:30:00Z",
      "updatedAt": "2024-08-13T15:30:00Z",
      "attendees": [
        {
          "name": "John Doe",
          "email": "[email protected]",
          "timeZone": "America/New_York",
          "absent": false,
          "language": "en",
          "phoneNumber": "+1234567890"
        }
      ],
      "bookingFieldsResponses": {
        "customField": "customValue"
      },
      "cancellationReason": "User requested cancellation",
      "cancelledByEmail": "[email protected]",
      "reschedulingReason": "User rescheduled the event",
      "rescheduledByEmail": "[email protected]",
      "rescheduledFromUid": "previous_uid_123",
      "rescheduledToUid": "new_uid_456",
      "meetingUrl": "https://example.com/recurring-meeting",
      "metadata": {
        "key": "value"
      },
      "rating": 4,
      "icsUid": "ics_uid_123",
      "guests": [
        "[email protected]",
        "[email protected]"
      ]
    }
  ],
  "pagination": {
    "totalItems": 123,
    "remainingItems": 103,
    "returnedItems": 10,
    "itemsPerPage": 10,
    "currentPage": 2,
    "totalPages": 13,
    "hasNextPage": true,
    "hasPreviousPage": true
  },
  "error": {}
}

GET

bookings

Get all bookings

curl --request GET \
  --url https://api.cal.com/v2/bookings \
  --header 'Authorization: <authorization>' \
  --header 'cal-api-version: <cal-api-version>'

{
  "status": "success",
  "data": [
    {
      "id": 123,
      "uid": "booking_uid_123",
      "title": "Consultation",
      "description": "Learn how to integrate scheduling into marketplace.",
      "hosts": [
        {
          "id": 1,
          "name": "Jane Doe",
          "email": "[email protected]",
          "username": "jane100",
          "timeZone": "America/Los_Angeles"
        }
      ],
      "status": "accepted",
      "start": "2024-08-13T15:30:00Z",
      "end": "2024-08-13T16:30:00Z",
      "duration": 60,
      "eventTypeId": 50,
      "eventType": {
        "id": 1,
        "slug": "some-event"
      },
      "location": "https://example.com/meeting",
      "absentHost": true,
      "createdAt": "2024-08-13T15:30:00Z",
      "updatedAt": "2024-08-13T15:30:00Z",
      "attendees": [
        {
          "name": "John Doe",
          "email": "[email protected]",
          "timeZone": "America/New_York",
          "absent": false,
          "language": "en",
          "phoneNumber": "+1234567890"
        }
      ],
      "bookingFieldsResponses": {
        "customField": "customValue"
      },
      "cancellationReason": "User requested cancellation",
      "cancelledByEmail": "[email protected]",
      "reschedulingReason": "User rescheduled the event",
      "rescheduledByEmail": "[email protected]",
      "rescheduledFromUid": "previous_uid_123",
      "rescheduledToUid": "new_uid_456",
      "meetingUrl": "https://example.com/recurring-meeting",
      "metadata": {
        "key": "value"
      },
      "rating": 4,
      "icsUid": "ics_uid_123",
      "guests": [
        "[email protected]",
        "[email protected]"
      ]
    }
  ],
  "pagination": {
    "totalItems": 123,
    "remainingItems": 103,
    "returnedItems": 10,
    "itemsPerPage": 10,
    "currentPage": 2,
    "totalPages": 13,
    "hasNextPage": true,
    "hasPreviousPage": true
  },
  "error": {}
}

Headers

cal-api-version

string

default:2024-08-13

required

Must be set to 2024-08-13. If not set to this value, the endpoint will default to an older version.

Authorization

string

required

value must be Bearer <token> where <token> is api key prefixed with cal_ or managed user access token

Query Parameters

status

enum<string>[]

Filter bookings by status. If you want to filter by multiple statuses, separate them with a comma.

Available options:

upcoming,

recurring,

past,

cancelled,

unconfirmed

attendeeEmail

string

Filter bookings by the attendee's email address.

attendeeName

string

Filter bookings by the attendee's name.

bookingUid

string

Filter bookings by the booking Uid.

eventTypeIds

string

Filter bookings by event type ids belonging to the user. Event type ids must be separated by a comma.

eventTypeId

string

Filter bookings by event type id belonging to the user.

teamsIds

string

Filter bookings by team ids that user is part of. Team ids must be separated by a comma.

teamId

string

Filter bookings by team id that user is part of

afterStart

string

Filter bookings with start after this date string.

beforeEnd

string

Filter bookings with end before this date string.

afterCreatedAt

string

Filter bookings that have been created after this date string.

beforeCreatedAt

string

Filter bookings that have been created before this date string.

afterUpdatedAt

string

Filter bookings that have been updated after this date string.

beforeUpdatedAt

string

Filter bookings that have been updated before this date string.

sortStart

enum<string>

Sort results by their start time in ascending or descending order.

Available options:

asc,

desc

sortEnd

enum<string>

Sort results by their end time in ascending or descending order.

Available options:

asc,

desc

sortCreated

enum<string>

Sort results by their creation time (when booking was made) in ascending or descending order.

Available options:

asc,

desc

sortUpdatedAt

enum<string>

Sort results by their updated time (for example when booking status changes) in ascending or descending order.

Available options:

asc,

desc

take

number

default:100

The number of items to return

skip

number

default:0

The number of items to skip

Response

200 - application/json

status

enum<string>

required

Available options:

success,

error

Example:

"success"

data

object[]

required

Array of booking data, which can contain either BookingOutput objects or RecurringBookingOutput objects

Option 1
Option 2
Option 3
Option 4

Show child attributes

data.id

number

required

Example:

123

data.uid

string

required

Example:

"booking_uid_123"

data.title

string

required

Example:

"Consultation"

data.description

string

required

Example:

"Learn how to integrate scheduling into marketplace."

data.hosts

object[]

required

Show child attributes

data.hosts.id

number

required

Example:

1

data.hosts.name

string

required

Example:

"Jane Doe"

data.hosts.email

string

required

Example:

"[email protected]"

data.hosts.username

string

required

Example:

"jane100"

data.hosts.timeZone

string

required

Example:

"America/Los_Angeles"

data.status

enum<string>

required

Available options:

cancelled,

accepted,

rejected,

pending

Example:

"accepted"

data.start

string

required

Example:

"2024-08-13T15:30:00Z"

data.end

string

required

Example:

"2024-08-13T16:30:00Z"

data.duration

number

required

Example:

60

data.eventTypeId

number

required

deprecated

Deprecated - rely on 'eventType' object containing the id instead.

Example:

50

data.eventType

object

required

Show child attributes

data.eventType.id

number

required

Example:

1

data.eventType.slug

string

required

Example:

"some-event"

data.location

string

required

Example:

"https://example.com/meeting"

data.absentHost

boolean

required

Example:

true

data.createdAt

string

required

Example:

"2024-08-13T15:30:00Z"

data.updatedAt

string

required

Example:

"2024-08-13T15:30:00Z"

data.attendees

object[]

required

Show child attributes

data.attendees.name

string

required

Example:

"John Doe"

data.attendees.email

string

required

Example:

"[email protected]"

data.attendees.timeZone

string

required

Example:

"America/New_York"

data.attendees.absent

boolean

required

Example:

false

data.attendees.language

enum<string>

Available options:

ar,

ca,

de,

es,

eu,

he,

id,

ja,

lv,

pl,

ro,

sr,

th,

vi,

az,

cs,

el,

es-419,

fi,

hr,

it,

km,

nl,

pt,

ru,

sv,

tr,

zh-CN,

bg,

da,

en,

et,

fr,

hu,

iw,

ko,

no,

pt-BR,

sk,

ta,

uk,

zh-TW,

bn

Example:

"en"

data.attendees.phoneNumber

string

Example:

"+1234567890"

data.bookingFieldsResponses

object

required

Booking field responses consisting of an object with booking field slug as keys and user response as values.

Example:

{ "customField": "customValue" }

data.cancellationReason

string

Example:

"User requested cancellation"

data.cancelledByEmail

string

Example:

"[email protected]"

data.reschedulingReason

string

Example:

"User rescheduled the event"

data.rescheduledByEmail

string

Example:

"[email protected]"

data.rescheduledFromUid

string

UID of the previous booking from which this booking was rescheduled.

Example:

"previous_uid_123"

data.rescheduledToUid

string

UID of the new booking to which this booking was rescheduled.

Example:

"new_uid_456"

data.meetingUrl

string

deprecated

Deprecated - rely on 'location' field instead.

Example:

"https://example.com/recurring-meeting"

data.metadata

object

Example:

{ "key": "value" }

data.rating

number

Example:

4

data.icsUid

string

UID of ICS event.

Example:

"ics_uid_123"

data.guests

string[]

Example:

["[email protected]", "[email protected]"]

pagination

object

required

Show child attributes

pagination.totalItems

number

required

The total number of items available across all pages, matching the query criteria.

Required range: x >= 0

Example:

123

pagination.remainingItems

number

required

The number of items remaining to be fetched after the current page. Calculated as: totalItems - (skip + itemsPerPage).

Required range: x >= 0

Example:

103

pagination.returnedItems

number

required

The number of items returned in the current page.

Example:

10

pagination.itemsPerPage

number

required

The maximum number of items requested per page.

Required range: x >= 1

Example:

10

pagination.currentPage

number

required

The current page number being returned.

Required range: x >= 1

Example:

2

pagination.totalPages

number

required

The total number of pages available.

Required range: x >= 0

Example:

13

pagination.hasNextPage

boolean

required

Indicates if there is a subsequent page available after the current one.

Example:

true

pagination.hasPreviousPage

boolean

required

Indicates if there is a preceding page available before the current one.

Example:

true

error

object

Refresh API Key Create a booking

⌘I

Getting Started

Platform / Managed Users

Platform / Webhooks

Orgs / Attributes

Orgs / Attributes / Options

Orgs / Bookings

Orgs / Delegation Credentials

Orgs / Memberships

Orgs / Roles

Orgs / Roles / Permissions

Orgs / Routing forms

Orgs / Schedules

Orgs / Teams

Orgs / Teams / Bookings

Orgs / Teams / Conferencing

Orgs / Teams / Event Types

Orgs / Teams / Event Types / Private Links

Orgs / Teams / Invite

Orgs / Teams / Memberships

Orgs / Teams / Roles

Orgs / Teams / Roles / Permissions

Orgs / Teams / Routing forms

Orgs / Teams / Routing forms / Responses

Orgs / Teams / Schedules

Orgs / Teams / Stripe

Orgs / Teams / Users / Schedules

Orgs / Teams / Workflows

Orgs / Users

Orgs / Users / Bookings

Orgs / Users / OOO

Orgs / Users / Schedules

Orgs / Webhooks

Api Keys

Bookings

Bookings / Guests

Cal Unified Calendars

Calendars

Conferencing

Destination Calendars

Event Types

Event Types / Webhooks

Event Types Private Links

Managed Orgs

Me

OAuth Clients

Organization Team Verified Resources

Routing forms

Schedules

Selected Calendars

Slots

Stripe

Teams

Teams / Event Types

Teams / Memberships

Teams / Schedules

Teams Verified Resources

Verified Resources

Webhooks

Headers

Query Parameters

Response