API Reference

Complete reference for the Calendly API — endpoints, parameters, schemas, and code examples for every supported operation.

The Calendly API v2 is a REST API that lets your application interact with Calendly scheduling data. Requests and responses use JSON, URLs follow a predictable resource-oriented pattern, and authentication uses OAuth 2.1 or personal access tokens.

Base URL

All API requests are made against the Calendly API server:

https://api.calendly.com

OAuth endpoints are served from a separate origin:

https://auth.calendly.com

Authentication

The API supports two authentication methods. Choose based on who will use your integration.

OAuth 2.1 + PKCE

Use OAuth when your integration is a public application that many Calendly users will install.

Personal access tokens

Use a personal access token when your integration is internal and only your team will use it.

Every request must include a bearer token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Scopes

New OAuth apps and personal access tokens must request explicit scopes before calling endpoints. Each operation page lists the scopes it requires.

Scope catalog

Browse all available read and write scopes and the endpoints each one unlocks.

Response format

Single-resource responses wrap the returned object under a resource key:

{
  "resource": {
    "uri": "https://api.calendly.com/users/ABCDEFGHIJKLMNOP",
    "name": "Pat Lee",
    "email": "[e-mail]"
  }
}

Collection responses wrap the array under collection and include a pagination object:

{
  "collection": [ /* ... */ ],
  "pagination": {
    "count": 20,
    "next_page": "https://api.calendly.com/event_types?page_token=abc123",
    "next_page_token": "abc123"
  }
}

Errors

Errors return a JSON object with title, message, and optional details:

{
  "title": "Invalid Argument",
  "message": "The request contains invalid or malformed arguments.",
  "details": [
    {
      "parameter": "organization",
      "message": "must be a valid URI"
    }
  ]
}

Status	Meaning
400	The request is malformed or contains invalid parameters.
401	The access token is missing, expired, or revoked.
403	The token is valid but lacks the required scope or permissions.
404	The requested resource does not exist.
422	The request is well-formed but was rejected by business rules.
429	You have exceeded a rate limit. Back off and retry.
500	An unexpected error occurred on the server.

Rate limiting

Rate limits are applied per user, per endpoint. Exceeded limits return 429 Too Many Requests. Endpoint-specific limits (for example, Create Event Invitee) may differ by billing tier — see the release notes for the current values.

Webhooks

Subscribe to Calendly events with webhook subscriptions to receive real-time notifications when invitees schedule, cancel, or reschedule meetings. Webhook endpoints are available under the Webhooks tag.

SDKs and tools

Calendly MCP Server

Connect Calendly to any MCP-compatible AI client with OAuth and DCR.

Migration guide

Moving from API v1? Follow the migration guide to update your integration.