Calendly Groups API

openapi: 3.1.0
info:
  title: Calendly Scheduling Activity Log Groups 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
servers:
- url: https://api.calendly.com
  description: Production Server
security:
- bearerAuth: []
tags:
- name: Groups
  description: Endpoints for listing and retrieving organization groups.
paths:
  /groups:
    get:
      operationId: listGroups
      summary: List groups
      description: Returns a paginated list of groups within the specified organization. Groups allow organizing users into teams for scheduling purposes.
      tags:
      - Groups
      parameters:
      - name: organization
        in: query
        required: true
        description: The URI of the organization whose groups to list.
        schema:
          type: string
          format: uri
      - $ref: '#/components/parameters/Count'
      - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successfully retrieved groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    type: array
                    items:
                      $ref: '#/components/schemas/Group'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /group_relationships:
    get:
      operationId: listGroupRelationships
      summary: List group relationships
      description: Returns a paginated list of group memberships, showing which users belong to which groups within an organization.
      tags:
      - Groups
      parameters:
      - name: group
        in: query
        description: The URI of the group to list relationships for.
        schema:
          type: string
          format: uri
      - name: organization
        in: query
        required: true
        description: The URI of the organization.
        schema:
          type: string
          format: uri
      - $ref: '#/components/parameters/Count'
      - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successfully retrieved group relationships
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    type: array
                    items:
                      $ref: '#/components/schemas/GroupRelationship'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Group:
      type: object
      description: A group within an organization for organizing users into teams.
      properties:
        uri:
          type: string
          format: uri
          description: The canonical URI of the group resource.
        name:
          type: string
          description: The name of the group.
        organization:
          type: string
          format: uri
          description: The URI of the organization.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the group was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the group was last updated.
    GroupRelationship:
      type: object
      description: A relationship between a user and a group within an organization.
      properties:
        uri:
          type: string
          format: uri
          description: The canonical URI of the group relationship.
        owner:
          type: string
          format: uri
          description: The URI of the user who is a member of the group.
        group:
          type: string
          format: uri
          description: The URI of the group.
        organization:
          type: string
          format: uri
          description: The URI of the organization.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the relationship was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the relationship was last updated.
    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.
    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.
  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'
  parameters:
    Count:
      name: count
      in: query
      description: The number of results to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    PageToken:
      name: page_token
      in: query
      description: A token for fetching the next page of results from a previous paginated response.
      schema:
        type: string
  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