Create a booking

curl --request POST \
  --url https://api.cal.com/v2/bookings \
  --header 'Content-Type: application/json' \
  --header 'cal-api-version: <cal-api-version>' \
  --data '
{
  "start": "2024-08-13T09:00:00Z",
  "attendee": {
    "name": "John Doe",
    "timeZone": "America/New_York",
    "email": "john.doe@example.com",
    "phoneNumber": "+919876543210",
    "language": "it"
  },
  "bookingFieldsResponses": {
    "customField": "customValue"
  },
  "eventTypeId": 123,
  "eventTypeSlug": "my-event-type",
  "username": "john-doe",
  "teamSlug": "john-doe",
  "organizationSlug": "acme-corp",
  "guests": [
    "guest1@example.com",
    "guest2@example.com"
  ],
  "meetingUrl": "https://example.com/meeting",
  "location": {
    "type": "address"
  },
  "metadata": {
    "key": "value"
  },
  "lengthInMinutes": 30,
  "routing": {
    "responseId": 123,
    "teamMemberIds": [
      101,
      102
    ]
  },
  "emailVerificationCode": "123456"
}
'

{
  "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": "jane100@example.com",
        "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": "john@example.com",
        "timeZone": "America/New_York",
        "absent": false,
        "language": "en",
        "phoneNumber": "+1234567890"
      }
    ],
    "bookingFieldsResponses": {
      "customField": "customValue"
    },
    "cancellationReason": "User requested cancellation",
    "cancelledByEmail": "canceller@example.com",
    "reschedulingReason": "User rescheduled the event",
    "rescheduledByEmail": "rescheduler@example.com",
    "rescheduledFromUid": "previous_uid_123",
    "rescheduledToUid": "new_uid_456",
    "meetingUrl": "https://example.com/recurring-meeting",
    "metadata": {
      "key": "value"
    },
    "rating": 4,
    "icsUid": "ics_uid_123",
    "guests": [
      "guest1@example.com",
      "guest2@example.com"
    ]
  }
}

Bookings

Create a booking

POST /v2/bookings is used to create regular bookings, recurring bookings and instant bookings. The request bodies for all 3 are almost the same except: If eventTypeId in the request body is id of a regular event, then regular booking is created.

If it is an id of a recurring event type, then recurring booking is created.

Meaning that the request bodies are equal but the outcome depends on what kind of event type it is with the goal of making it as seamless for developers as possible.

For team event types it is possible to create instant meeting. To do that just pass "instant": true to the request body.

The start needs to be in UTC aka if the timezone is GMT+2 in Rome and meeting should start at 11, then UTC time should have hours 09:00 aka without time zone.

Finally, there are 2 ways to book an event type belonging to an individual user:

Provide eventTypeId in the request body.
Provide eventTypeSlug and username and optionally organizationSlug if the user with the username is within an organization.

And 2 ways to book and event type belonging to a team:

Provide eventTypeId in the request body.
Provide eventTypeSlug and teamSlug and optionally organizationSlug if the team with the teamSlug is within an organization.

If you are creating 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.

For event types that have SMS reminders workflow, you need to pass the attendee’s phone number in the request body via attendee.phoneNumber (e.g., “+19876543210” in international format). This is an optional field, but becomes required when SMS reminders are enabled for the event type. For the complete attendee object structure, see the attendee object documentation.

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.

POST

bookings

Create a booking

curl --request POST \
  --url https://api.cal.com/v2/bookings \
  --header 'Content-Type: application/json' \
  --header 'cal-api-version: <cal-api-version>' \
  --data '
{
  "start": "2024-08-13T09:00:00Z",
  "attendee": {
    "name": "John Doe",
    "timeZone": "America/New_York",
    "email": "john.doe@example.com",
    "phoneNumber": "+919876543210",
    "language": "it"
  },
  "bookingFieldsResponses": {
    "customField": "customValue"
  },
  "eventTypeId": 123,
  "eventTypeSlug": "my-event-type",
  "username": "john-doe",
  "teamSlug": "john-doe",
  "organizationSlug": "acme-corp",
  "guests": [
    "guest1@example.com",
    "guest2@example.com"
  ],
  "meetingUrl": "https://example.com/meeting",
  "location": {
    "type": "address"
  },
  "metadata": {
    "key": "value"
  },
  "lengthInMinutes": 30,
  "routing": {
    "responseId": 123,
    "teamMemberIds": [
      101,
      102
    ]
  },
  "emailVerificationCode": "123456"
}
'

{
  "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": "jane100@example.com",
        "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": "john@example.com",
        "timeZone": "America/New_York",
        "absent": false,
        "language": "en",
        "phoneNumber": "+1234567890"
      }
    ],
    "bookingFieldsResponses": {
      "customField": "customValue"
    },
    "cancellationReason": "User requested cancellation",
    "cancelledByEmail": "canceller@example.com",
    "reschedulingReason": "User rescheduled the event",
    "rescheduledByEmail": "rescheduler@example.com",
    "rescheduledFromUid": "previous_uid_123",
    "rescheduledToUid": "new_uid_456",
    "meetingUrl": "https://example.com/recurring-meeting",
    "metadata": {
      "key": "value"
    },
    "rating": 4,
    "icsUid": "ics_uid_123",
    "guests": [
      "guest1@example.com",
      "guest2@example.com"
    ]
  }
}

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

Body

application/json

Accepts different types of booking input: Create Booking (Option 1), Create Instant Booking (Option 2), or Create Recurring Booking (Option 3)

Option 1
Option 2
Option 3

start

string

required

The start time of the booking in ISO 8601 format in UTC timezone.

Example:

"2024-08-13T09:00:00Z"

attendee

object

required

The attendee's details.

Show child attributes

attendee.name

string

required

The name of the attendee.

Example:

"John Doe"

attendee.timeZone

string

required

The time zone of the attendee.

Example:

"America/New_York"

attendee.email

string

The email of the attendee.

Example:

"john.doe@example.com"

attendee.phoneNumber

string

The phone number of the attendee in international format.

Example:

"+919876543210"

attendee.language

enum<string>

default:en

The preferred language of the attendee. Used for booking confirmation.

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:

"it"

bookingFieldsResponses

object

Booking field responses consisting of an object with booking field slug as keys and user response as values for custom booking fields added by you.

Example:

{ "customField": "customValue" }

eventTypeId

number

The ID of the event type that is booked. Required unless eventTypeSlug and username are provided as an alternative to identifying the event type.

Example:

123

eventTypeSlug

string

The slug of the event type. Required along with username / teamSlug and optionally organizationSlug if eventTypeId is not provided.

Example:

"my-event-type"

username

string

The username of the event owner. Required along with eventTypeSlug and optionally organizationSlug if eventTypeId is not provided.

Example:

"john-doe"

teamSlug

string

Team slug for team that owns event type for which slots are fetched. Required along with eventTypeSlug and optionally organizationSlug if the team is part of organization

Example:

"john-doe"

organizationSlug

string

The organization slug. Optional, only used when booking with eventTypeSlug + username or eventTypeSlug + teamSlug.

Example:

"acme-corp"

guests

string[]

An optional list of guest emails attending the event.

Example:

["guest1@example.com", "guest2@example.com"]

meetingUrl

string

deprecated

Deprecated - use 'location' instead. Meeting URL just for this booking. Displayed in email and calendar event. If not provided then cal video link will be generated.

Example:

"https://example.com/meeting"

location

object

One of the event type locations. If instead of passing one of the location objects as required by schema you are still passing a string please use an object.

Option 1
Option 2
Option 3
Option 4
Option 5
Option 6
Option 7
Option 8

Show child attributes

location.type

string

required

only allowed value for type is address - it refers to address defined by the organizer.

Example:

"address"

metadata

object

You can store any additional data you want here. Metadata must have at most 50 keys, each key up to 40 characters, and string values up to 500 characters.

Example:

{ "key": "value" }

lengthInMinutes

number

If it is an event type that has multiple possible lengths that attendee can pick from, you can pass the desired booking length here. If not provided then event type default length will be used for the booking.

Example:

30

routing

object

Routing information from routing forms that determined the booking assignment. Both responseId and teamMemberIds are required if provided.

Show child attributes

routing.teamMemberIds

number[]

required

Array of team member IDs that were routed to handle this booking.

Example:

[101, 102]

routing.queuedResponseId

string | null

The ID of the queued form response. Only present if the form response was queued.

Example:

"123"

routing.responseId

number | null

The ID of the routing form response.

Example:

123

routing.teamMemberEmail

string

The email of the team member assigned to handle this booking.

Example:

"john.doe@example.com"

routing.skipContactOwner

boolean

Whether to skip contact owner assignment from CRM integration.

Example:

true

routing.crmAppSlug

string

The CRM application slug for integration.

Example:

"salesforce"

routing.crmOwnerRecordType

string

The CRM owner record type for contact assignment.

Example:

"Account"

Example:

{
  "responseId": 123,
  "teamMemberIds": [101, 102]
}

emailVerificationCode

string

Email verification code required when event type has email verification enabled.

Example:

"123456"

Response

201 - application/json

status

enum<string>

required

Available options:

success,

error

Example:

"success"

data

object

required

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

Option 1 · object
Option 2 · object[]
Option 3 · object
Option 4 · 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:

"jane100@example.com"

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:

"john@example.com"

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:

"canceller@example.com"

data.reschedulingReason

string

Example:

"User rescheduled the event"

data.rescheduledByEmail

string

Example:

"rescheduler@example.com"

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:

["guest1@example.com", "guest2@example.com"]

Get all bookings Get 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

Body

Response