Calendly Users API

openapi: 3.2.0
info:
  title: Calendly Scheduling Activity Log Users 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: Users
  description: Endpoints for retrieving user information and managing user accounts within Calendly.
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'
components:
  schemas:
    User:
      type: object
      description: A Calendly user account with scheduling and organization information.
      properties:
        uri:
          type: string
          format: uri
          description: The canonical URI of the user resource.
        name:
          type: string
          description: The full name of the user.
        slug:
          type: string
          description: The URL-friendly slug for the users scheduling page.
        email:
          type: string
          format: email
          description: The email address of the user.
        scheduling_url:
          type: string
          format: uri
          description: The URL of the users Calendly scheduling page.
        timezone:
          type: string
          description: The IANA timezone of the user.
        avatar_url:
          type: string
          format: uri
          description: The URL of the users avatar image.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the user was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the user was last updated.
        current_organization:
          type: string
          format: uri
          description: The URI of the users current organization.
    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.
  parameters:
    UserUuid:
      name: uuid
      in: path
      required: true
      description: The UUID of the user.
      schema:
        type: string
  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'
    NotFound:
      description: The requested resource was not found. Verify the UUID or URI is correct.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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