Calendly Scheduling API

openapi: 3.1.0
info:
  title: Calendly Scheduling API
  description: >-
    The Calendly Scheduling API (v2) is a RESTful API that allows developers
    to programmatically manage scheduling workflows. It provides endpoints for
    managing users, organizations, event types, scheduled events, invitees,
    routing forms, availability schedules, and webhook subscriptions. The API
    uses JSON for request and response bodies, standard HTTP methods, and
    supports authentication via personal access tokens and OAuth 2.1.
    Developers can use it to create events on behalf of invitees, retrieve
    scheduling data, and integrate Calendly functionality directly into their
    applications.
  version: '2.0.0'
  contact:
    name: Calendly Developer Support
    url: https://developer.calendly.com/
  termsOfService: https://calendly.com/pages/terms
externalDocs:
  description: Calendly API Documentation
  url: https://developer.calendly.com/api-docs
servers:
  - url: https://api.calendly.com
    description: Production Server
tags:
  - name: Activity Log
    description: >-
      Endpoints for retrieving activity log entries for an organization.
  - name: Availability
    description: >-
      Endpoints for viewing available times for event types and managing
      user availability schedules.
  - name: Data Compliance
    description: >-
      Endpoints for handling data compliance requests such as deletion
      and retrieval of invitee data.
  - name: Event Types
    description: >-
      Endpoints for listing, retrieving, and managing event types that define
      the kinds of meetings users can schedule.
  - name: Groups
    description: >-
      Endpoints for listing and retrieving organization groups.
  - name: Invitees
    description: >-
      Endpoints for listing, retrieving, and creating invitees on scheduled
      events.
  - name: Organizations
    description: >-
      Endpoints for managing organization memberships, invitations, and
      organization-level settings.
  - name: Routing Forms
    description: >-
      Endpoints for listing and retrieving routing forms and their
      submissions.
  - name: Scheduled Events
    description: >-
      Endpoints for listing, retrieving, and canceling scheduled events
      (booked meetings).
  - name: Shares
    description: >-
      Endpoints for creating and managing shareable scheduling links.
  - name: Users
    description: >-
      Endpoints for retrieving user information and managing user accounts
      within Calendly.
  - name: Webhook Subscriptions
    description: >-
      Endpoints for creating, listing, retrieving, and deleting webhook
      subscriptions that receive real-time event notifications.
security:
  - bearerAuth: []
paths:
  /users/me:
    get:
      operationId: getCurrentUser
      summary: Get current user
      description: >-
        Returns information about the currently authenticated user, including
        their URI, name, email, scheduling URL, timezone, and organization
        membership.
      tags:
        - Users
      responses:
        '200':
          description: Successfully retrieved the current user
          content:
            application/json:
              schema:
                type: object
                properties:
                  resource:
                    $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{uuid}:
    get:
      operationId: getUser
      summary: Get user
      description: >-
        Returns information about a specific user by their UUID, including
        name, email, scheduling URL, timezone, and organization.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/UserUuid'
      responses:
        '200':
          description: Successfully retrieved the user
          content:
            application/json:
              schema:
                type: object
                properties:
                  resource:
                    $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /event_types:
    get:
      operationId: listEventTypes
      summary: List event types
      description: >-
        Returns a paginated list of event types for the specified user or
        organization. Event types define the kinds of meetings that can be
        scheduled, including their duration, location, and availability.
      tags:
        - Event Types
      parameters:
        - name: user
          in: query
          description: >-
            The URI of the user whose event types to list. Required if
            organization is not specified.
          schema:
            type: string
            format: uri
        - name: organization
          in: query
          description: >-
            The URI of the organization whose event types to list. Required if
            user is not specified.
          schema:
            type: string
            format: uri
        - name: active
          in: query
          description: >-
            Filter by active status. When true, only active event types are
            returned.
          schema:
            type: boolean
        - name: sort
          in: query
          description: >-
            Sort order for results. Use name:asc or name:desc.
          schema:
            type: string
        - $ref: '#/components/parameters/Count'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successfully retrieved the list of event types
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    type: array
                    items:
                      $ref: '#/components/schemas/EventType'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /event_types/{uuid}:
    get:
      operationId: getEventType
      summary: Get event type
      description: >-
        Returns detailed information about a specific event type by its UUID,
        including its name, duration, scheduling URL, and configuration.
      tags:
        - Event Types
      parameters:
        - $ref: '#/components/parameters/EventTypeUuid'
      responses:
        '200':
          description: Successfully retrieved the event type
          content:
            application/json:
              schema:
                type: object
                properties:
                  resource:
                    $ref: '#/components/schemas/EventType'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /one_off_event_types:
    post:
      operationId: createOneOffEventType
      summary: Create one-off event type
      description: >-
        Creates a single-use event type that can be used for a one-time
        scheduling session. One-off event types are not listed on the users
        scheduling page.
      tags:
        - Event Types
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - host
                - duration
                - date_setting
              properties:
                name:
                  type: string
                  description: >-
                    The name of the one-off event type.
                host:
                  type: string
                  format: uri
                  description: >-
                    The URI of the user who will host the event.
                duration:
                  type: integer
                  description: >-
                    The duration of the event in minutes.
                  minimum: 1
                date_setting:
                  type: object
                  description: >-
                    Date range settings for the one-off event type.
                  properties:
                    type:
                      type: string
                      enum:
                        - date_range
                    start_date:
                      type: string
                      format: date
                    end_date:
                      type: string
                      format: date
                location:
                  type: object
                  description: >-
                    The location configuration for the event.
      responses:
        '201':
          description: Successfully created the one-off event type
          content:
            application/json:
              schema:
                type: object
                properties:
                  resource:
                    $ref: '#/components/schemas/EventType'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /event_type_available_times:
    get:
      operationId: listEventTypeAvailableTimes
      summary: List event type available times
      description: >-
        Returns a list of available time slots for a specific event type within
        a given date range. This endpoint is used to display bookable times to
        potential invitees.
      tags:
        - Availability
      parameters:
        - name: event_type
          in: query
          required: true
          description: >-
            The URI of the event type to check availability for.
          schema:
            type: string
            format: uri
        - name: start_time
          in: query
          required: true
          description: >-
            The start of the time range to check, in UTC format.
          schema:
            type: string
            format: date-time
        - name: end_time
          in: query
          required: true
          description: >-
            The end of the time range to check, in UTC format.
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Successfully retrieved available times
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    type: array
                    items:
                      $ref: '#/components/schemas/AvailableTime'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /user_busy_times:
    get:
      operationId: listUserBusyTimes
      summary: List user busy times
      description: >-
        Returns a list of time periods during which a user is busy, based on
        their connected calendars. Useful for checking a users availability
        before scheduling.
      tags:
        - Availability
      parameters:
        - name: user
          in: query
          required: true
          description: >-
            The URI of the user whose busy times to retrieve.
          schema:
            type: string
            format: uri
        - name: start_time
          in: query
          required: true
          description: >-
            The start of the time range to check, in UTC format.
          schema:
            type: string
            format: date-time
        - name: end_time
          in: query
          required: true
          description: >-
            The end of the time range to check, in UTC format.
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Successfully retrieved busy times
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    type: array
                    items:
                      $ref: '#/components/schemas/BusyTime'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /user_availability_schedules:
    get:
      operationId: listUserAvailabilitySchedules
      summary: List user availability schedules
      description: >-
        Returns a list of availability schedules for a specific user. Availability
        schedules define the recurring time windows when a user is available for
        meetings.
      tags:
        - Availability
      parameters:
        - name: user
          in: query
          required: true
          description: >-
            The URI of the user whose availability schedules to retrieve.
          schema:
            type: string
            format: uri
      responses:
        '200':
          description: Successfully retrieved availability schedules
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    type: array
                    items:
                      $ref: '#/components/schemas/AvailabilitySchedule'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /user_availability_schedules/{uuid}:
    get:
      operationId: getUserAvailabilitySchedule
      summary: Get user availability schedule
      description: >-
        Returns a specific availability schedule by its UUID, including the
        timezone and rules that define available time windows.
      tags:
        - Availability
      parameters:
        - name: uuid
          in: path
          required: true
          description: >-
            The UUID of the availability schedule.
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved the availability schedule
          content:
            application/json:
              schema:
                type: object
                properties:
                  resource:
                    $ref: '#/components/schemas/AvailabilitySchedule'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /scheduled_events:
    get:
      operationId: listScheduledEvents
      summary: List scheduled events
      description: >-
        Returns a paginated list of scheduled events for the specified user or
        organization. Scheduled events represent booked meetings with start and
        end times, locations, and associated invitees.
      tags:
        - Scheduled Events
      parameters:
        - name: user
          in: query
          description: >-
            The URI of the user whose scheduled events to list.
          schema:
            type: string
            format: uri
        - name: organization
          in: query
          description: >-
            The URI of the organization whose scheduled events to list.
          schema:
            type: string
            format: uri
        - name: invitee_email
          in: query
          description: >-
            Filter by invitee email address.
          schema:
            type: string
            format: email
        - name: status
          in: query
          description: >-
            Filter by event status.
          schema:
            type: string
            enum:
              - active
              - canceled
        - name: min_start_time
          in: query
          description: >-
            Only return events starting on or after this time, in UTC format.
          schema:
            type: string
            format: date-time
        - name: max_start_time
          in: query
          description: >-
            Only return events starting before this time, in UTC format.
          schema:
            type: string
            format: date-time
        - name: sort
          in: query
          description: >-
            Sort order for results. Use start_time:asc or start_time:desc.
          schema:
            type: string
        - $ref: '#/components/parameters/Count'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successfully retrieved the list of scheduled events
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    type: array
                    items:
                      $ref: '#/components/schemas/ScheduledEvent'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /scheduled_events/{uuid}:
    get:
      operationId: getScheduledEvent
      summary: Get scheduled event
      description: >-
        Returns detailed information about a specific scheduled event by its
        UUID, including start and end times, event type, location, and
        cancellation details if applicable.
      tags:
        - Scheduled Events
      parameters:
        - $ref: '#/components/parameters/ScheduledEventUuid'
      responses:
        '200':
          description: Successfully retrieved the scheduled event
          content:
            application/json:
              schema:
                type: object
                properties:
                  resource:
                    $ref: '#/components/schemas/ScheduledEvent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /scheduled_events/{uuid}/cancellation:
    post:
      operationId: cancelScheduledEvent
      summary: Cancel scheduled event
      description: >-
        Cancels a scheduled event. Optionally include a reason for the
        cancellation. This will trigger invitee.canceled webhook events
        for all subscribed endpoints.
      tags:
        - Scheduled Events
      parameters:
        - $ref: '#/components/parameters/ScheduledEventUuid'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: >-
                    The reason for canceling the event.
                  maxLength: 10000
      responses:
        '200':
          description: Successfully canceled the scheduled event
          content:
            application/json:
              schema:
                type: object
                properties:
                  resource:
                    $ref: '#/components/schemas/Cancellation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /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'
  /webhook_subscriptions:
    get:
      operationId: listWebhookSubscriptions
      summary: List webhook subscriptions
      description: >-
        Returns a paginated list of webhook subscriptions for the specified
        user or organization. Each subscription defines the events to listen
        for and the callback URL to notify.
      tags:
        - Webhook Subscriptions
      parameters:
        - name: user
          in: query
          description: >-
            The URI of the user whose webhook subscriptions to list.
          schema:
            type: string
            format: uri
        - name: organization
          in: query
          required: true
          description: >-
            The URI of the organization whose webhook subscriptions to list.
          schema:
            type: string
            format: uri
        - name: scope
          in: query
          required: true
          description: >-
            The scope of the webhook subscription. Use user for subscriptions
            scoped to a specific user, or organization for organization-wide
            subscriptions.
          schema:
            type: string
            enum:
              - user
              - organization
        - $ref: '#/components/parameters/Count'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successfully retrieved webhook subscriptions
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookSubscription'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWebhookSubscription
      summary: Create webhook subscription
      description: >-
        Creates a new webhook subscription to receive real-time notifications
        when scheduling events occur. You can subscribe to invitee.created,
        invitee.canceled, and routing_form_submission.created events.
      tags:
        - Webhook Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
                - events
                - organization
                - scope
              properties:
                url:
                  type: string
                  format: uri
                  description: >-
                    The URL where webhook payloads will be delivered.
                events:
                  type: array
                  items:
                    type: string
                    enum:
                      - invitee.created
                      - invitee.canceled
                      - routing_form_submission.created
                  description: >-
                    The list of event types to subscribe to.
                  minItems: 1
                organization:
                  type: string
                  format: uri
                  description: >-
                    The URI of the organization for the subscription.
                user:
                  type: string
                  format: uri
                  description: >-
                    The URI of the user for user-scoped subscriptions.
                scope:
                  type: string
                  enum:
                    - user
                    - organization
                  description: >-
                    The scope of the webhook subscription.
                signing_key:
                  type: string
                  description: >-
                    A secret key used to sign webhook payloads for
                    verification.
      responses:
        '201':
          description: Successfully created the webhook subscription
          content:
            application/json:
              schema:
                type: object
                properties:
                  resource:
                    $ref: '#/components/schemas/WebhookSubscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhook_subscriptions/{uuid}:
    get:
      operationId: getWebhookSubscription
      summary: Get webhook subscription
      description: >-
        Returns detailed information about a specific webhook subscription
        by its UUID, including the callback URL, subscribed events, and scope.
      tags:
        - Webhook Subscriptions
      parameters:
        - $ref: '#/components/parameters/WebhookSubscriptionUuid'
      responses:
        '200':
          description: Successfully retrieved the webhook subscription
          content:
            application/json:
              schema:
                type: object
                properties:
                  resource:
                    $ref: '#/components/schemas/WebhookSubscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteWebhookSubscription
      summary: Delete webhook subscription
      description: >-
        Deletes a webhook subscription by its UUID. Once deleted, the
        subscription will no longer receive event notifications.
      tags:
        - Webhook Subscriptions
      parameters:
        - $ref: '#/components/parameters/WebhookSubscriptionUuid'
      responses:
        '204':
          description: Successfully deleted the webhook subscription
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /organization_memberships:
    get:
      operationId: listOrganizationMemberships
      summary: List organization memberships
      description: >-
        Returns a paginated list of organization memberships. Each membership
        represents a users role and status within an organization.
      tags:
        - Organizations
      parameters:
        - name: organization
          in: query
          required: true
          description: >-
            The URI of the organization whose memberships to list.
          schema:
            type: string
            format: uri
        - name: user
          in: query
          description: >-
            Filter by user URI.
          schema:
            type: string
            format: uri
        - name: email
          in: query
          description: >-
            Filter by user email address.
          schema:
            type: string
            format: email
        - $ref: '#/components/parameters/Count'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successfully retrieved organization memberships
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    type: array
                    items:
                      $ref: '#/components/schemas/OrganizationMembership'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /organization_memberships/{uuid}:
    get:
      operationId: getOrganizationMembership
      summary: Get organization membership
      description: >-
        Returns detailed information about a spec

# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/calendly/refs/heads/main/openapi/calendly-scheduling-api-openapi.yml