---
title: "Add guests to an existing booking"
method: POST
path: "/v2/bookings/{bookingUid}/guests"
tags: ["Bookings / Guests"]
---

# Add guests to an existing booking

`POST /v2/bookings/{bookingUid}/guests`

## Request

- The document declares no server URL.
- Auth: none declared. Required headers: `cal-api-version`, `Authorization`

Add one or more guests to an existing booking. Maximum 10 guests per request, with a limit of 30 total guests per booking.
    
    **Rate Limiting:**
    This endpoint is rate limited to 5 requests per minute to prevent abuse.
    
    **Email Notifications:**
    When guests are added, the following notifications are sent (unless disabled by event type settings):
    
    - **Organizer & Team Members:** Receive an "Add Guests" notification email informing them that new guests have been added to the booking.
    
    - **New Guests:** Receive a "Scheduled Event" email with full booking details and calendar invite. If they have a phone number, they also receive an SMS notification.
    
    - **Existing Guests:** Receive an "Add Guests" notification email informing them that additional guests have been added to the booking.
    
    <Note>The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error.</Note>

## Path parameters

- `bookingUid` string, required

## Headers

- `cal-api-version` string, required
- `Authorization` string, required

## Request body

- AddGuestsInput20240813
  - `guests` Guest[], required: Array of guests to add to the booking. Maximum 10 guests per request.
    - `email` string, required: The email of the guest.
    - `name` string: The name of the guest.
    - `timeZone` string: The time zone of the guest.
    - `phoneNumber` string: The phone number of the guest 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 guest. Used for booking confirmation.

## Response `200`

- AddGuestsOutput20240813
  - `status` 'success' | 'error', required
  - `data` union, required: Booking data, which can be either a BookingOutput object, a RecurringBookingOutput 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
    - 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
    - GetSeatedBookingOutput20240813
      - `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` 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
    - GetRecurringSeatedBookingOutput20240813
      - `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` 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
    - GetRecurringSeatedBookingOutput20240813[]
      - `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` 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

## Changes

- **2026-02-02** (v2) `2c269d910f84`: 1 breaking
  - the `guests` request property's minItems was increased to `1`
- **2026-01-12** (v2) `a3b94595a3bd`: 1 breaking, 9 info
  - added `subschema #3, subschema #6` to the `data` response property `oneOf` list for the response status `200`
  - removed `subschema #3, subschema #6` from the `data` response property `oneOf` list for the response status `200`
  - added the required property `data/oneOf[#/components/schemas/BookingOutput_2024_08_13]/attendees/items/displayEmail` to the response with the `200` status
  - added the required property `data/oneOf[#/components/schemas/BookingOutput_2024_08_13]/hosts/items/displayEmail` to the response with the `200` status
  - …6 more
- **2025-10-28** (v2) `a0be8c9beb32`: 1 info
  - endpoint added
- **2025-09-26** (v2) `daa3e48bc03a`: 1 breaking
  - api path removed without deprecation

[Operation history](https://skmtc.dev/calcom/apis/cal-diy-api-v2/changes/v2/bookings/:bookingUid/guests/post.md)

---

[API](https://skmtc.dev/calcom/apis/cal-diy-api-v2.md) - [All operations](https://skmtc.dev/calcom/apis/cal-diy-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/calcom/apis/cal-diy-api-v2/revisions/cac5ec02a46b?raw)