Calendly Invitees API

openapi: 3.2.0
info:
  title: Calendly Scheduling Invitees API
  description: The Calendly Scheduling API (v2) is a RESTful API that allows developers to programmatically manage scheduling workflows.
  version: 2.0.0
  contact:
    name: Calendly Developer Support
    url: https://developer.calendly.com/
  termsOfService: https://calendly.com/pages/terms
servers:
- url: https://api.calendly.com
  description: Production Server
security:
- bearerAuth: []
tags:
- name: Invitees
  description: Endpoints for listing, retrieving, and creating invitees on scheduled events.
paths:
  /scheduled_events/{event_uuid}/invitees:
    get:
      operationId: listEventInvitees
      summary: List event invitees
      description: Returns a paginated list of invitees for a specific scheduled event. Invitee data includes name, email, timezone, and answers to custom questions from the booking page.
      tags:
      - Invitees
      parameters:
      - name: event_uuid
        in: path
        required: true
        description: The UUID of the scheduled event.
        schema:
          type: string
      - name: status
        in: query
        description: Filter by invitee status.
        schema:
          type: string
          enum:
          - active
          - canceled
      - name: sort
        in: query
        description: Sort order for results. Use created_at:asc or created_at:desc.
        schema:
          type: string
      - $ref: '#/components/parameters/Count'
      - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successfully retrieved the list of invitees
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invitee'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /scheduled_events/{event_uuid}/invitees/{invitee_uuid}:
    get:
      operationId: getEventInvitee
      summary: Get event invitee
      description: Returns detailed information about a specific invitee for a scheduled event, including their name, email, timezone, and answers to custom questions on the event booking page.
      tags:
      - Invitees
      parameters:
      - name: event_uuid
        in: path
        required: true
        description: The UUID of the scheduled event.
        schema:
          type: string
      - name: invitee_uuid
        in: path
        required: true
        description: The UUID of the invitee.
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved the invitee
          content:
            application/json:
              schema:
                type: object
                properties:
                  resource:
                    $ref: '#/components/schemas/Invitee'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /invitees:
    post:
      operationId: createEventInvitee
      summary: Create event invitee
      description: Creates a new invitee for a scheduled event, effectively booking a meeting on behalf of the invitee. This is the core endpoint of the Scheduling API, enabling programmatic event creation without redirects, iframes, or the Calendly-hosted UI. Requires a paid Calendly plan.
      tags:
      - Invitees
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - event_type
              - start_time
              - invitee
              properties:
                event_type:
                  type: string
                  format: uri
                  description: The URI of the event type to book.
                start_time:
                  type: string
                  format: date-time
                  description: The start time for the event in UTC. Must correspond to a valid available time slot.
                invitee:
                  type: object
                  required:
                  - name
                  - email
                  properties:
                    name:
                      type: string
                      description: The full name of the invitee.
                    email:
                      type: string
                      format: email
                      description: The email address of the invitee.
                    timezone:
                      type: string
                      description: The IANA timezone of the invitee.
                  description: The invitee details for the booking.
                questions_and_answers:
                  type: array
                  items:
                    type: object
                    properties:
                      question_uuid:
                        type: string
                        description: The UUID of the custom question.
                      answer:
                        type: string
                        description: The answer to the custom question.
                  description: Answers to custom questions on the event type booking page.
      responses:
        '201':
          description: Successfully created the invitee and booked the event
          content:
            application/json:
              schema:
                type: object
                properties:
                  resource:
                    $ref: '#/components/schemas/Invitee'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Authentication failed. Verify that a valid access token is provided in the Authorization header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was invalid or malformed. Check the request body and parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found. Verify the UUID or URI is correct.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Invitee:
      type: object
      description: An invitee is a person who has booked or been booked for a scheduled event, with their contact information and booking details.
      properties:
        uri:
          type: string
          format: uri
          description: The canonical URI of the invitee resource.
        email:
          type: string
          format: email
          description: The email address of the invitee.
        first_name:
          type: string
          description: The first name of the invitee.
        last_name:
          type: string
          description: The last name of the invitee.
        name:
          type: string
          description: The full name of the invitee.
        status:
          type: string
          enum:
          - active
          - canceled
          description: The status of the invitee.
        timezone:
          type: string
          description: The IANA timezone of the invitee.
        event:
          type: string
          format: uri
          description: The URI of the associated scheduled event.
        text_reminder_number:
          type: string
          description: The phone number for text reminders.
        rescheduled:
          type: boolean
          description: Whether this invitee was rescheduled from a previous event.
        old_invitee:
          type: string
          format: uri
          description: The URI of the previous invitee if this was rescheduled.
        new_invitee:
          type: string
          format: uri
          description: The URI of the new invitee if this invitee was rescheduled.
        cancel_url:
          type: string
          format: uri
          description: The URL for the invitee to cancel the event.
        reschedule_url:
          type: string
          format: uri
          description: The URL for the invitee to reschedule the event.
        routing_form_submission:
          type: string
          format: uri
          description: The URI of the routing form submission that led to this booking.
        cancellation:
          $ref: '#/components/schemas/Cancellation'
        payment:
          type: object
          description: Payment information if the event type requires payment.
          properties:
            external_id:
              type: string
              description: The external payment processor ID.
            provider:
              type: string
              description: The payment provider name.
            amount:
              type: number
              description: The payment amount.
            currency:
              type: string
              description: The payment currency code.
            terms:
              type: string
              description: The payment terms.
            successful:
              type: boolean
              description: Whether the payment was successful.
        questions_and_answers:
          type: array
          items:
            type: object
            properties:
              question:
                type: string
                description: The text of the custom question.
              answer:
                type: string
                description: The invitees answer to the question.
              position:
                type: integer
                description: The display position of the question.
          description: The invitees answers to custom questions on the booking page.
        tracking:
          type: object
          description: UTM and tracking parameters captured at booking time.
          properties:
            utm_campaign:
              type: string
              description: The UTM campaign parameter.
            utm_source:
              type: string
              description: The UTM source parameter.
            utm_medium:
              type: string
              description: The UTM medium parameter.
            utm_content:
              type: string
              description: The UTM content parameter.
            utm_term:
              type: string
              description: The UTM term parameter.
            salesforce_uuid:
              type: string
              description: The Salesforce UUID if applicable.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the invitee was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the invitee was last updated.
    Cancellation:
      type: object
      description: Information about a canceled event or invitee, including who canceled and the reason.
      properties:
        canceled_by:
          type: string
          description: The name or identifier of who canceled the event.
        reason:
          type: string
          description: The reason provided for the cancellation.
        canceler_type:
          type: string
          enum:
          - host
          - invitee
          description: Whether the host or invitee canceled.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the cancellation occurred.
    Error:
      type: object
      description: An error response from the Calendly API.
      properties:
        title:
          type: string
          description: A short summary of the error.
        message:
          type: string
          description: A detailed description of the error.
        details:
          type: array
          items:
            type: object
            properties:
              parameter:
                type: string
                description: The parameter that caused the error.
              message:
                type: string
                description: A description of what was wrong with the parameter.
          description: Specific details about validation errors.
    Pagination:
      type: object
      description: Pagination information for paginated list responses.
      properties:
        count:
          type: integer
          description: The number of results in the current page.
        next_page:
          type: string
          format: uri
          description: The URL of the next page of results, if available.
        previous_page:
          type: string
          format: uri
          description: The URL of the previous page of results, if available.
        next_page_token:
          type: string
          description: The token to fetch the next page of results.
        previous_page_token:
          type: string
          description: The token to fetch the previous page of results.
  parameters:
    PageToken:
      name: page_token
      in: query
      description: A token for fetching the next page of results from a previous paginated response.
      schema:
        type: string
    Count:
      name: count
      in: query
      description: The number of results to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Personal access token or OAuth 2.1 access token. Include in the Authorization header as Bearer {token}.
externalDocs:
  description: Calendly API Documentation
  url: https://developer.calendly.com/api-docs