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. If the event type has an instant meeting schedule, requests made outside it, or too close to its end for the meeting to fit, are rejected with a 400.

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:

1. Provide eventTypeId in the request body.
2. 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:

1. Provide eventTypeId in the request body.
2. 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., “[phone]” 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 /v2/bookings

Create a booking

cURL

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",
    "phoneNumber": "[phone]",
    "language": "it",
    "email": "[e-mail]"
  },
  "bookingFieldsResponses": {
    "customField": "customValue"
  },
  "leadEnrichmentOptOut": false,
  "eventTypeId": 123,
  "eventTypeSlug": "my-event-type",
  "username": "john-doe",
  "teamSlug": "john-doe",
  "organizationSlug": "acme-corp",
  "usernames": [
    "alice",
    "bob"
  ],
  "guests": [
    "[e-mail]",
    "[e-mail]"
  ],
  "meetingUrl": "https://example.com/meeting",
  "location": {
    "type": "address"
  },
  "metadata": {
    "key": "value"
  },
  "lengthInMinutes": 30,
  "routing": {
    "responseId": 123,
    "teamMemberIds": [
      101,
      102
    ]
  },
  "emailVerificationCode": "123456",
  "allowConflicts": true,
  "allowBookingOutOfBounds": true,
  "skipBookingLimits": true
}
'

201

{
  "status": "success",
  "data": {
    "id": 123,
    "uid": "booking_uid_123",
    "title": "Consultation",
    "description": "Learn how to integrate scheduling into marketplace.",
    "hosts": [
      {
        "id": 1,
        "uuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
        "name": "Jane Doe",
        "email": "[e-mail]",
        "displayEmail": "[e-mail]",
        "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": "[e-mail]",
        "displayEmail": "[e-mail]",
        "timeZone": "America/New_York",
        "absent": false,
        "language": "en",
        "phoneNumber": "[phone]"
      }
    ],
    "bookingFieldsResponses": {
      "customField": "customValue"
    },
    "cancellationReason": "User requested cancellation",
    "cancelledByEmail": "[e-mail]",
    "reschedulingReason": "User rescheduled the event",
    "rescheduledByEmail": "[e-mail]",
    "rescheduledFromUid": "previous_uid_123",
    "rescheduledToUid": "new_uid_456",
    "eventUuid": "0199b5d2-7c1e-7f3a-9b4d-2e6f8a1c3d5e",
    "meetingUrl": "https://example.com/recurring-meeting",
    "metadata": {
      "key": "value"
    },
    "rating": 4,
    "icsUid": "ics_uid_123",
    "guests": [
      "[e-mail]",
      "[e-mail]"
    ]
  }
}

Headers

cal-api-version · string · default: 2026-02-25 · required

Must be set to 2026-02-25.

Example:

"2026-02-25"

Authorization · string

value must be Bearer <token> where <token> is api key prefixed with cal_, managed user access token, or OAuth 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: Standard Booking, Instant Booking, or Recurring Booking.

Standard Booking

Instant Booking

Recurring Booking

start · string<date-time> · 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

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

leadEnrichmentOptOut · boolean

The booker's answer to the lead enrichment opt-out, for an event type with a workflow that looks bookers up with lead enrichment. Send true when the booker ticked the opt-out and false when they were shown it and left it unticked. Sending false asserts that the booker saw the opt-out. Leave it out when the booker was not shown it: a booking without an answer is never looked up.

Example:

false

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, eventTypeSlug + teamSlug, or usernames.

Example:

"acme-corp"

usernames · string[]

Usernames of the hosts for a dynamic group booking (no stored event type) - every listed user must be available. Must contain 2 to 20 distinct usernames, and can't be combined with eventTypeId, eventTypeSlug, username or teamSlug. Pass organizationSlug when the users belong to an organization; without it only users outside any organization are found. Platform managed users can only be booked with their own OAuth client's credentials or one of its access tokens; to any other request they are reported as not found. Duration defaults to 30 minutes and can be changed with lengthInMinutes (15, 30, 45, 60 or 90).

Required array length: 2 - 20 elements

Example:

["alice", "bob"]

guests · string[]

An optional list of guest emails attending the event.

Example:

["[e-mail]", "[e-mail]"]

meetingUrl · string<uri> · 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 · Address · 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.

Address

Attendee Address

Attendee Defined

Attendee Phone

Integration

Link

Phone

Organizer Default App

Show child attributes

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.

Show child attributes

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.

Required range: x >= 1

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

Example:

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

emailVerificationCode · string

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

Example:

"123456"

allowConflicts · boolean

When true, availability conflict checks are bypassed for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.

Example:

true

allowBookingOutOfBounds · boolean

When true, booking time out-of-bounds checks are bypassed, allowing bookings outside the normally permitted scheduling window, for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.

Example:

true

skipBookingLimits · boolean

When true, booking limit checks (event type, team, and per-host count and duration limits) are bypassed for an authenticated user who has access through the existing event owner, host, assigned user, team admin or organization admin checks. Team- and organization-scoped keys are restricted to events in their stored team or organization. Otherwise this parameter is silently ignored. Only supported on the 2026-02-25 and 2026-05-01 API versions.

Example:

true

Response

201 - application/json

status · enum<string> · required

Available options: success, error

Example:

"success"

data · Booking · object · required

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

Booking · object

Instant Booking · object

Recurring Bookings (array) · object[]

Seated Booking · object

Recurring Seated Bookings (array) · object[]

Show child attributes