---
title: "Create a booking"
method: POST
path: "/v2/bookings"
tags: ["Bookings"]
---

# Create a booking

`POST /v2/bookings`

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.

      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 enabled, 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 schema in the `/docs` Swagger endpoint.

      <Note>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.</Note>

## Headers

- `cal-api-version` string, required
- `Authorization` string
- `x-cal-secret-key` string
- `x-cal-client-id` string

## Request body

- union
  - CreateBookingInput20240813
    - `start` string, required — The start time of the booking in ISO 8601 format in UTC timezone.
    - `attendee` CreateBookingAttendee, required
      - `name` string, required — The name of the attendee.
      - `timeZone` string, required — The time zone of the attendee.
      - `phoneNumber` string — The phone number of the attendee in international format.
      - `language` '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' — The preferred language of the attendee. Used for booking confirmation.
      - `email` string — The email of the attendee.
    - `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.
    - `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.
    - `eventTypeSlug` string — The slug of the event type. Required along with username / teamSlug and optionally organizationSlug if eventTypeId is not provided.
    - `username` string — The username of the event owner. Required along with eventTypeSlug and optionally organizationSlug if eventTypeId is not provided.
    - `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
    - `organizationSlug` string — The organization slug. Optional, only used when booking with eventTypeSlug + username or eventTypeSlug + teamSlug.
    - `guests` string[] — An optional list of guest emails attending the event.
    - `meetingUrl` string — 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.
    - `location` union — 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.
      - BookingInputAddressLocation20240813
        - `type` string, required — only allowed value for type is `address` - it refers to address defined by the organizer.
      - BookingInputAttendeeAddressLocation20240813
        - `type` string, required — only allowed value for type is `attendeeAddress`
        - `address` string, required
      - BookingInputAttendeeDefinedLocation20240813
        - `type` string, required — only allowed value for type is `attendeeDefined`
        - `location` string, required
      - BookingInputAttendeePhoneLocation20240813
        - `type` string, required — only allowed value for type is `attendeePhone`
        - `phone` string, required
      - BookingInputIntegrationLocation20240813
        - `type` string, required — only allowed value for type is `integration`
        - `integration` 'cal-video' | 'google-meet' | 'zoom' | 'whereby-video' | 'whatsapp-video' | 'webex-video' | 'telegram-video' | 'tandem' | 'sylaps-video' | 'skype-video' | 'sirius-video' | 'signal-video' | 'shimmer-video' | 'salesroom-video' | 'roam-video' | 'riverside-video' | 'ping-video' | 'office365-video' | 'mirotalk-video' | 'jitsi' | 'jelly-video' | 'jelly-conferencing' | 'huddle' | 'facetime-video' | 'element-call-video' | 'eightxeight-video' | 'discord-video' | 'demodesk-video' | 'campfire-video', required
      - BookingInputLinkLocation20240813
        - `type` string, required — only allowed value for type is `link` - it refers to link defined by the organizer.
      - BookingInputPhoneLocation20240813
        - `type` string, required — only allowed value for type is `phone` - it refers to phone defined by the organizer.
      - BookingInputOrganizersDefaultAppLocation20240813
        - `type` string, required — only available for team event types and the only allowed value for type is `organizersDefaultApp` - it refers to the default app defined by the organizer.
    - `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.
    - `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.
    - `routing` Routing
      - `responseId` number, required — The ID of the routing form response that determined this booking assignment.
      - `teamMemberIds` number[], required — Array of team member IDs that were routed to handle this booking.
      - `teamMemberEmail` string — The email of the team member assigned to handle this booking.
      - `skipContactOwner` boolean — Whether to skip contact owner assignment from CRM integration.
      - `crmAppSlug` string — The CRM application slug for integration.
      - `crmOwnerRecordType` string — The CRM owner record type for contact assignment.
    - `emailVerificationCode` string — Email verification code required when event type has email verification enabled.
  - CreateRecurringBookingInput20240813
    - `start` string, required — The start time of the booking in ISO 8601 format in UTC timezone.
    - `attendee` CreateBookingAttendee, required
      - `name` string, required — The name of the attendee.
      - `timeZone` string, required — The time zone of the attendee.
      - `phoneNumber` string — The phone number of the attendee in international format.
      - `language` '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' — The preferred language of the attendee. Used for booking confirmation.
      - `email` string — The email of the attendee.
    - `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.
    - `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.
    - `eventTypeSlug` string — The slug of the event type. Required along with username / teamSlug and optionally organizationSlug if eventTypeId is not provided.
    - `username` string — The username of the event owner. Required along with eventTypeSlug and optionally organizationSlug if eventTypeId is not provided.
    - `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
    - `organizationSlug` string — The organization slug. Optional, only used when booking with eventTypeSlug + username or eventTypeSlug + teamSlug.
    - `guests` string[] — An optional list of guest emails attending the event.
    - `meetingUrl` string — 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.
    - `location` union — 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.
      - BookingInputAddressLocation20240813
        - `type` string, required — only allowed value for type is `address` - it refers to address defined by the organizer.
      - BookingInputAttendeeAddressLocation20240813
        - `type` string, required — only allowed value for type is `attendeeAddress`
        - `address` string, required
      - BookingInputAttendeeDefinedLocation20240813
        - `type` string, required — only allowed value for type is `attendeeDefined`
        - `location` string, required
      - BookingInputAttendeePhoneLocation20240813
        - `type` string, required — only allowed value for type is `attendeePhone`
        - `phone` string, required
      - BookingInputIntegrationLocation20240813
        - `type` string, required — only allowed value for type is `integration`
        - `integration` 'cal-video' | 'google-meet' | 'zoom' | 'whereby-video' | 'whatsapp-video' | 'webex-video' | 'telegram-video' | 'tandem' | 'sylaps-video' | 'skype-video' | 'sirius-video' | 'signal-video' | 'shimmer-video' | 'salesroom-video' | 'roam-video' | 'riverside-video' | 'ping-video' | 'office365-video' | 'mirotalk-video' | 'jitsi' | 'jelly-video' | 'jelly-conferencing' | 'huddle' | 'facetime-video' | 'element-call-video' | 'eightxeight-video' | 'discord-video' | 'demodesk-video' | 'campfire-video', required
      - BookingInputLinkLocation20240813
        - `type` string, required — only allowed value for type is `link` - it refers to link defined by the organizer.
      - BookingInputPhoneLocation20240813
        - `type` string, required — only allowed value for type is `phone` - it refers to phone defined by the organizer.
      - BookingInputOrganizersDefaultAppLocation20240813
        - `type` string, required — only available for team event types and the only allowed value for type is `organizersDefaultApp` - it refers to the default app defined by the organizer.
    - `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.
    - `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.
    - `routing` Routing
      - `responseId` number, required — The ID of the routing form response that determined this booking assignment.
      - `teamMemberIds` number[], required — Array of team member IDs that were routed to handle this booking.
      - `teamMemberEmail` string — The email of the team member assigned to handle this booking.
      - `skipContactOwner` boolean — Whether to skip contact owner assignment from CRM integration.
      - `crmAppSlug` string — The CRM application slug for integration.
      - `crmOwnerRecordType` string — The CRM owner record type for contact assignment.
    - `emailVerificationCode` string — Email verification code required when event type has email verification enabled.
    - `recurrenceCount` number — The number of recurrences. If not provided then event type recurrence count will be used. Can't be more than event type recurrence count

## Response `201`

- CreateBookingOutput20240813
  - `status` 'success' | 'error', required
  - `data` union, required — Booking data, which can be either a BookingOutput object or an array of RecurringBookingOutput objects
    - BookingOutput20240813
      - `id` number, required
      - `uid` string, required
      - `title` string, required
      - `description` string, required
      - `hosts` BookingHost[], required
        - `id` number, required
        - `name` string, required
        - `email` string, required
        - `displayEmail` string, required — Clean email for display purposes
        - `username` string, required
        - `timeZone` string, required
      - `status` 'cancelled' | 'accepted' | 'rejected' | 'pending', required
      - `cancellationReason` string
      - `cancelledByEmail` string
      - `reschedulingReason` string
      - `rescheduledByEmail` string
      - `rescheduledFromUid` string — UID of the previous booking from which this booking was rescheduled.
      - `rescheduledToUid` string — UID of the new booking to which this booking was rescheduled.
      - `start` string, required
      - `end` string, required
      - `duration` number, required
      - `eventTypeId` number, required — Deprecated - rely on 'eventType' object containing the id instead.
      - `eventType` EventType, required
        - `id` number, required
        - `slug` string, required
      - `meetingUrl` string — Deprecated - rely on 'location' field instead.
      - `location` string, required
      - `absentHost` boolean, required
      - `createdAt` string, required
      - `updatedAt` string, required
      - `metadata` object
      - `rating` number
      - `icsUid` string — UID of ICS event.
      - `attendees` BookingAttendee[], required
        - `name` string, required
        - `email` string, required
        - `displayEmail` string, required — Clean email for display purposes
        - `timeZone` string, required
        - `language` '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'
        - `absent` boolean, required
        - `phoneNumber` string
      - `guests` string[]
      - `bookingFieldsResponses` object, required — Booking field responses consisting of an object with booking field slug as keys and user response as values.
    - RecurringBookingOutput20240813[]
      - `id` number, required
      - `uid` string, required
      - `title` string, required
      - `description` string, required
      - `hosts` BookingHost[], required
        - `id` number, required
        - `name` string, required
        - `email` string, required
        - `displayEmail` string, required — Clean email for display purposes
        - `username` string, required
        - `timeZone` string, required
      - `status` 'cancelled' | 'accepted' | 'rejected' | 'pending', required
      - `cancellationReason` string
      - `cancelledByEmail` string
      - `reschedulingReason` string
      - `rescheduledByEmail` string
      - `rescheduledFromUid` string — UID of the previous booking from which this booking was rescheduled.
      - `rescheduledToUid` string — UID of the new booking to which this booking was rescheduled.
      - `start` string, required
      - `end` string, required
      - `duration` number, required
      - `eventTypeId` number, required — Deprecated - rely on 'eventType' object containing the id instead.
      - `eventType` EventType, required
        - `id` number, required
        - `slug` string, required
      - `meetingUrl` string — Deprecated - rely on 'location' field instead.
      - `location` string, required
      - `absentHost` boolean, required
      - `createdAt` string, required
      - `updatedAt` string, required
      - `metadata` object
      - `rating` number
      - `icsUid` string — UID of ICS event.
      - `attendees` BookingAttendee[], required
        - `name` string, required
        - `email` string, required
        - `displayEmail` string, required — Clean email for display purposes
        - `timeZone` string, required
        - `language` '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'
        - `absent` boolean, required
        - `phoneNumber` string
      - `guests` string[]
      - `bookingFieldsResponses` object, required — Booking field responses consisting of an object with booking field slug as keys and user response as values.
      - `recurringBookingUid` string, required
    - CreateSeatedBookingOutput20240813
      - `id` number, required
      - `uid` string, required
      - `title` string, required
      - `description` string, required
      - `hosts` BookingHost[], required
        - `id` number, required
        - `name` string, required
        - `email` string, required
        - `displayEmail` string, required — Clean email for display purposes
        - `username` string, required
        - `timeZone` string, required
      - `status` 'cancelled' | 'accepted' | 'rejected' | 'pending', required
      - `cancellationReason` string
      - `cancelledByEmail` string
      - `reschedulingReason` string
      - `rescheduledByEmail` string
      - `rescheduledFromUid` string — UID of the previous booking from which this booking was rescheduled.
      - `rescheduledToUid` string — UID of the new booking to which this booking was rescheduled.
      - `start` string, required
      - `end` string, required
      - `duration` number, required
      - `eventTypeId` number, required — Deprecated - rely on 'eventType' object containing the id instead.
      - `eventType` EventType, required
        - `id` number, required
        - `slug` string, required
      - `meetingUrl` string — Deprecated - rely on 'location' field instead.
      - `location` string, required
      - `absentHost` boolean, required
      - `createdAt` string, required
      - `updatedAt` string, required
      - `metadata` object
      - `rating` number
      - `icsUid` string — UID of ICS event.
      - `seatUid` string, required
      - `attendees` SeatedAttendee[], required
        - `name` string, required
        - `email` string, required
        - `displayEmail` string, required — Clean email for display purposes
        - `timeZone` string, required
        - `language` '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'
        - `absent` boolean, required
        - `phoneNumber` string
        - `seatUid` string, required
        - `bookingFieldsResponses` object, required — Booking field responses consisting of an object with booking field slug as keys and user response as values.
        - `metadata` object
    - CreateRecurringSeatedBookingOutput20240813[]
      - `id` number, required
      - `uid` string, required
      - `title` string, required
      - `description` string, required
      - `hosts` BookingHost[], required
        - `id` number, required
        - `name` string, required
        - `email` string, required
        - `displayEmail` string, required — Clean email for display purposes
        - `username` string, required
        - `timeZone` string, required
      - `status` 'cancelled' | 'accepted' | 'rejected' | 'pending', required
      - `cancellationReason` string
      - `cancelledByEmail` string
      - `reschedulingReason` string
      - `rescheduledByEmail` string
      - `rescheduledFromUid` string — UID of the previous booking from which this booking was rescheduled.
      - `rescheduledToUid` string — UID of the new booking to which this booking was rescheduled.
      - `start` string, required
      - `end` string, required
      - `duration` number, required
      - `eventTypeId` number, required — Deprecated - rely on 'eventType' object containing the id instead.
      - `eventType` EventType, required
        - `id` number, required
        - `slug` string, required
      - `meetingUrl` string — Deprecated - rely on 'location' field instead.
      - `location` string, required
      - `absentHost` boolean, required
      - `createdAt` string, required
      - `updatedAt` string, required
      - `metadata` object
      - `rating` number
      - `icsUid` string — UID of ICS event.
      - `seatUid` string, required
      - `attendees` SeatedAttendee[], required
        - `name` string, required
        - `email` string, required
        - `displayEmail` string, required — Clean email for display purposes
        - `timeZone` string, required
        - `language` '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'
        - `absent` boolean, required
        - `phoneNumber` string
        - `seatUid` string, required
        - `bookingFieldsResponses` object, required — Booking field responses consisting of an object with booking field slug as keys and user response as values.
        - `metadata` object
      - `recurringBookingUid` string, required

---

[API](https://skmtc.net/calcom/apis/cal-diy-api-v2.md) · [All operations](https://skmtc.net/calcom/apis/cal-diy-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/calcom/cal-diy-api-v2/versions/16de9d3eb7b3/schema)