Cal.com Bookings / Attendees API

openapi: 3.2.0
info:
  title: Cal.diy API v2 Api Keys Bookings / Attendees API
  description: ''
  version: 1.0.0
  contact: {}
servers: []
tags:
- name: Bookings / Attendees
paths:
  /v2/bookings/{bookingUid}/attendees:
    get:
      operationId: BookingAttendeesController_2024_08_13_getBookingAttendees
      summary: Get all attendees for a booking
      description: "Retrieve all attendees for a specific booking by its UID.\n    \n    <Note>The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error.</Note>\n    "
      parameters:
      - name: cal-api-version
        in: header
        description: Must be set to 2024-08-13. This header is required as this endpoint does not exist in older API versions.
        required: true
        schema:
          type: string
      - name: bookingUid
        required: true
        in: path
        schema:
          type: string
      - name: Authorization
        in: header
        description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBookingAttendeesOutput_2024_08_13'
      tags:
      - Bookings / Attendees
    post:
      operationId: BookingAttendeesController_2024_08_13_addAttendee
      summary: Add an attendee to a booking
      description: "Add a new attendee to an existing booking by its UID.\n\n      **Side effects:**\n      - The booking's attendee list is updated in the database\n      - The calendar event is updated on connected calendars (Google Calendar, Outlook, etc.) to include the new attendee\n      - An email notification is sent to the new attendee with the booking details\n\n      **Permissions:**\n      - The authenticated user must be either the booking organizer, an existing attendee, or have the `booking.update` permission for the team\n\n      <Note>The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error.</Note>\n      "
      parameters:
      - name: cal-api-version
        in: header
        description: Must be set to 2024-08-13. This header is required as this endpoint does not exist in older API versions.
        required: true
        schema:
          type: string
      - name: bookingUid
        required: true
        in: path
        schema:
          type: string
      - name: Authorization
        in: header
        description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddAttendeeInput_2024_08_13'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddAttendeeOutput_2024_08_13'
      tags:
      - Bookings / Attendees
  /v2/bookings/{bookingUid}/attendees/{attendeeId}:
    get:
      operationId: BookingAttendeesController_2024_08_13_getBookingAttendee
      summary: Get a specific attendee for a booking
      description: "Retrieve a specific attendee by their ID for a booking identified by its UID.\n        \n      <Note>The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error.</Note>\n      "
      parameters:
      - name: cal-api-version
        in: header
        description: Must be set to 2024-08-13. This header is required as this endpoint does not exist in older API versions.
        required: true
        schema:
          type: string
      - name: bookingUid
        required: true
        in: path
        schema:
          type: string
      - name: attendeeId
        required: true
        in: path
        schema:
          type: number
      - name: Authorization
        in: header
        description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBookingAttendeeOutput_2024_08_13'
      tags:
      - Bookings / Attendees
    delete:
      operationId: BookingAttendeesController_2024_08_13_removeAttendee
      summary: Remove an attendee from a booking
      description: "Remove an attendee from an existing booking by their attendee ID. The primary attendee (first attendee) cannot be removed — to remove them, cancel the booking instead. The removed attendee will receive a cancellation email notification.\n\n    <Note>The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error.</Note>\n    "
      parameters:
      - name: cal-api-version
        in: header
        description: Must be set to 2024-08-13. This header is required as this endpoint does not exist in older API versions.
        required: true
        schema:
          type: string
      - name: bookingUid
        required: true
        in: path
        schema:
          type: string
      - name: attendeeId
        required: true
        in: path
        schema:
          type: number
      - name: Authorization
        in: header
        description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveAttendeeOutput_2024_08_13'
      tags:
      - Bookings / Attendees
components:
  schemas:
    AddAttendeeOutput_2024_08_13:
      type: object
      properties:
        status:
          type: string
          example: success
          enum:
          - success
          - error
        data:
          $ref: '#/components/schemas/BookingAttendeeOutput_2024_08_13'
      required:
      - status
      - data
    RemovedAttendeeOutput_2024_08_13:
      type: object
      properties:
        id:
          type: number
          description: The ID of the attendee.
          example: 123
        bookingId:
          type: number
          description: The ID of the booking.
          example: 456
        name:
          type: string
          description: The name of the attendee.
          example: John Doe
        email:
          type: string
          description: The email of the attendee.
          example: john.doe@example.com
        timeZone:
          type: string
          description: The time zone of the attendee.
          example: America/New_York
      required:
      - id
      - bookingId
      - name
      - email
      - timeZone
    GetBookingAttendeesOutput_2024_08_13:
      type: object
      properties:
        status:
          type: string
          example: success
          enum:
          - success
          - error
        data:
          type: array
          items:
            $ref: '#/components/schemas/BookingAttendeeWithId_2024_08_13'
      required:
      - status
      - data
    BookingAttendeeWithId_2024_08_13:
      type: object
      properties:
        name:
          type: string
          example: John Doe
        email:
          type: string
          example: john@example.com
        displayEmail:
          type: string
          example: john@example.com
          description: Clean email for display purposes
        timeZone:
          type: string
          example: America/New_York
        language:
          type: string
          enum:
          - 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
        absent:
          type: boolean
          example: false
        phoneNumber:
          type: string
          example: '+1234567890'
        id:
          type: number
          example: 251
      required:
      - name
      - email
      - displayEmail
      - timeZone
      - absent
      - id
    GetBookingAttendeeOutput_2024_08_13:
      type: object
      properties:
        status:
          type: string
          example: success
          enum:
          - success
          - error
        data:
          $ref: '#/components/schemas/BookingAttendeeWithId_2024_08_13'
      required:
      - status
      - data
    RemoveAttendeeOutput_2024_08_13:
      type: object
      properties:
        status:
          type: string
          example: success
          enum:
          - success
          - error
        data:
          $ref: '#/components/schemas/RemovedAttendeeOutput_2024_08_13'
      required:
      - status
      - data
    BookingAttendeeOutput_2024_08_13:
      type: object
      properties:
        name:
          type: string
          example: John Doe
        email:
          type: string
          example: john@example.com
        displayEmail:
          type: string
          example: john@example.com
          description: Clean email for display purposes
        timeZone:
          type: string
          example: America/New_York
        language:
          type: string
          enum:
          - 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
        absent:
          type: boolean
          example: false
        phoneNumber:
          type: string
          example: '+1234567890'
        id:
          type: number
          example: 251
        bookingId:
          type: number
          example: 313
      required:
      - name
      - email
      - displayEmail
      - timeZone
      - absent
      - id
      - bookingId
    AddAttendeeInput_2024_08_13:
      type: object
      properties:
        name:
          type: string
          description: The name of the attendee.
          example: John Doe
        timeZone:
          type: string
          description: The time zone of the attendee.
          example: America/New_York
        phoneNumber:
          type: string
          description: The phone number of the attendee in international format.
          example: '+919876543210'
        language:
          type: string
          enum:
          - 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
          description: The preferred language of the attendee. Used for booking confirmation.
          example: it
          default: en
        email:
          type: string
          description: The email of the attendee.
          example: john.doe@example.com
      required:
      - name
      - timeZone
      - email