Get a booking

curl --request GET \
  --url https://api.cal.com/v2/bookings/{bookingUid} \
  --header 'Authorization: Bearer <token>' \
  --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]"
    ]
  },
  "error": {}
}

Bookings

Get a booking

:bookingUid can be

uid of a normal booking
uid of one of the recurring booking recurrences
uid of recurring booking which will return an array of all recurring booking recurrences (stored as recurringBookingUid on one of the individual recurrences).

If you are fetching a seated booking for an event type with ‘show attendees’ disabled, then to retrieve attendees in the response either set ‘show attendees’ to true on event type level or you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.

Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.

GET

bookings

{bookingUid}

Get a booking

curl --request GET \
  --url https://api.cal.com/v2/bookings/{bookingUid} \
  --header 'Authorization: Bearer <token>' \
  --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]"
    ]
  },
  "error": {}
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

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

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

x-cal-secret-key

string

For platform customers - OAuth client secret key

x-cal-client-id

string

For platform customers - OAuth client ID

Path Parameters

bookingUid

string

required

Response

200 - application/json

status

enum<string>

required

Available options:

success,

error

Example:

"success"

data

object

required

Booking data, which can be either a BookingOutput object, a RecurringBookingOutput object, or an array of RecurringBookingOutput objects

Option 1 · object
Option 2 · object
Option 3 · object[]
Option 4 · object
Option 5 · object
Option 6 · object[]

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]"]

error

object

Create a booking Get all the recordings for the 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

Authorizations

Headers

Path Parameters

Response