A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Calendly API is how an app or AI agent works with a Calendly account: listing event types, reading scheduled events and their invitees, booking a meeting, canceling one, and managing the people in an organization. Access is granted through a personal access token or an OAuth token, and a set of scopes in a resource:action shape decides which areas a call can read or write. A booking or a cancellation can emit an event that Calendly delivers to a registered webhook.
How an app or AI agent connects to Calendly determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes Calendly tools to agents, and each is governed by the token behind it and the scopes that token carries.
The REST API answers at https://api.calendly.com. It takes JSON request and response bodies, uses standard HTTP methods, and identifies resources by URI. Lists are cursor-paginated through a page_token, with a default page size of 20 and a maximum of 100. It is a single, continuously updated v2 API with no dated version header.
Calendly POSTs an event to an HTTPS URL registered through the Create Webhook Subscription endpoint. A subscription is scoped to a user or the whole organization and chooses which events to receive, like invitee.created or invitee.canceled. The receiver verifies the Calendly-Webhook-Signature header against the subscription's signing key. Webhooks require a paid Standard, Teams, or Enterprise plan.
A hosted Model Context Protocol server at https://mcp.calendly.com exposes Calendly tools to AI agents and MCP clients, mapped to the public v2 API. It authenticates with OAuth 2.1 authorization code plus PKCE using Dynamic Client Registration, so a client self-registers for a client_id at runtime rather than pasting in pre-provisioned credentials, and uses the mcp:scheduling:read and mcp:scheduling:write scopes. Tools cover retrieving event types, finding available times, changing availability, getting booking links, creating scheduled events, and canceling appointments.
A personal access token is created in the account's API and Webhooks settings and acts as that single user. It is sent as a Bearer token in the Authorization header. A new token grants no API access until scopes are requested and approved; a legacy token issued before scoped permissions keeps full access until refreshed. It is the simpler choice for an internal integration used by one team.
OAuth lets an app act on behalf of any Calendly user who authorizes it. The user is sent to https://auth.calendly.com/oauth/authorize with a client_id, redirect_uri, response_type=code, and a space-separated list of scopes, and the returned code is exchanged for an access token. The token response also carries the user's owner and organization URIs. Calendly uses OAuth 2.1 with authorization code and PKCE.
The Calendly API is split into areas an agent can act on, like event types, scheduled events, invitees, availability, and the organization's members. Each area has its own methods and its own scopes, and a write can book a meeting, cancel an event, or remove a person from the organization.
Read the current user and read a user by their unique reference.
List event types for a user or organization, read a single event type, and create a one-off event type.
List and read scheduled events (meetings), and cancel one.
List and read the invitees on a scheduled event, and book a meeting by creating an invitee.
List an event type's available times, a user's busy times, and a user's availability schedules.
Create a single-use scheduling link that an invitee can use once to book.
List and read the organization's members, remove a member, and list, send, read, or revoke invitations.
List, read, create, and delete webhook subscriptions.
Delete the stored data for one or more invitees.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
UsersRead the current user and read a user by their unique reference.2 | ||||||
| GET | /users/me | Get the current user, the owner of the access token. | read | users:read | Current | |
With OAuth, the owner and organization URIs also come back in the access token response. Acts onuser Permission (capability) users:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /users/{uuid} | Get a user by their unique reference. | read | users:read | Current | |
Read-only. Acts onuser Permission (capability) users:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Event typesList event types for a user or organization, read a single event type, and create a one-off event type.3 | ||||||
| GET | /event_types | List event types for a user or for an organization. | read | event_types:read | Current | |
Pass either a user or an organization parameter to set the scope of the list. Acts onevent type Permission (capability) event_types:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /event_types/{uuid} | Get a single event type. | read | event_types:read | Current | |
Read-only. Acts onevent type Permission (capability) event_types:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /one_off_event_types | Create a one-off event type, a single-use meeting type for one or more hosts. | write | event_types:write | Current | |
event_types:write also covers creating and updating standard event types. Acts onevent type Permission (capability) event_types:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Scheduled eventsList and read scheduled events (meetings), and cancel one.3 | ||||||
| GET | /scheduled_events | List scheduled events (meetings) for a user or an organization. | read | scheduled_events:read | Current | |
Filter by user, organization, invitee email, status, and time range. Acts onscheduled event Permission (capability) scheduled_events:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /scheduled_events/{uuid} | Get a single scheduled event. | read | scheduled_events:read | Current | |
Read-only. Acts onscheduled event Permission (capability) scheduled_events:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /scheduled_events/{uuid}/cancellation | Cancel a scheduled event. | write | scheduled_events:write | Current | |
Cancels the meeting and notifies invitees; rescheduling is not a direct API call. Acts onscheduled event Permission (capability) scheduled_events:writeVersionAvailable since the API’s base version Webhook event invitee.canceledRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Invitees & bookingList and read the invitees on a scheduled event, and book a meeting by creating an invitee.3 | ||||||
| GET | /scheduled_events/{event_uuid}/invitees | List the invitees on a scheduled event. | read | scheduled_events:read | Current | |
Returns invitee names, emails, answers to custom questions, and tracking parameters. Acts oninvitee Permission (capability) scheduled_events:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /scheduled_events/{event_uuid}/invitees/{invitee_uuid} | Get a single invitee on a scheduled event. | read | scheduled_events:read | Current | |
Used to fetch the full invitee detail referenced from a webhook payload. Acts oninvitee Permission (capability) scheduled_events:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /invitees | Book a meeting by creating an invitee on an event type, with no redirect or hosted page. | write | scheduled_events:write | New | |
Part of the Scheduling API, generally available 16 Oct 2025; the Calendly account must be on a paid plan. Acts oninvitee Permission (capability) scheduled_events:writeVersionIntroduced 2025-10-16 Webhook event invitee.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AvailabilityList an event type's available times, a user's busy times, and a user's availability schedules.4 | ||||||
| GET | /event_type_available_times | List the available booking times for an event type within a date range. | read | availability:read | Current | |
The range is capped at 7 days per request. Acts onavailable time Permission (capability) availability:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /user_busy_times | List a user's busy times, internal Calendly events and external calendar events combined. | read | availability:read | Current | |
The range is capped at 7 days per request. Acts onbusy time Permission (capability) availability:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /user_availability_schedules | List a user's availability schedules (the weekly hours they can be booked). | read | availability:read | Current | |
Read-only. Acts onavailability schedule Permission (capability) availability:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /user_availability_schedules/{uuid} | Get a single user availability schedule. | read | availability:read | Current | |
Read-only. Acts onavailability schedule Permission (capability) availability:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Scheduling linksCreate a single-use scheduling link that an invitee can use once to book.1 | ||||||
| POST | /scheduling_links | Create a single-use scheduling link an invitee can use once to book. | write | scheduling_links:write | Current | |
An unused link expires after 90 days. Built on a chosen event type. Acts onscheduling link Permission (capability) scheduling_links:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Organization & membersList and read the organization's members, remove a member, and list, send, read, or revoke invitations.7 | ||||||
| GET | /organization_memberships | List the members of an organization. | read | organizations:read | Current | |
Filter by organization, user, or email. Acts onorganization membership Permission (capability) organizations:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /organization_memberships/{uuid} | Get a single organization membership. | read | organizations:read | Current | |
Read-only. Acts onorganization membership Permission (capability) organizations:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /organization_memberships/{uuid} | Remove a member from an organization. | write | organizations:write | Current | |
Removes the person's access to the organization. Acts onorganization membership Permission (capability) organizations:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /organizations/{uuid}/invitations | List the invitations sent for an organization. | read | organizations:read | Current | |
Read-only. Acts onorganization invitation Permission (capability) organizations:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /organizations/{uuid}/invitations | Invite a person to an organization by email. | write | organizations:write | Current | |
Sends an invitation email to the address provided. Acts onorganization invitation Permission (capability) organizations:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /organizations/{org_uuid}/invitations/{invitation_uuid} | Get a single organization invitation. | read | organizations:read | Current | |
Read-only. Acts onorganization invitation Permission (capability) organizations:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /organizations/{org_uuid}/invitations/{invitation_uuid} | Revoke a pending organization invitation. | write | organizations:write | Current | |
Cancels an invitation that has not yet been accepted. Acts onorganization invitation Permission (capability) organizations:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList, read, create, and delete webhook subscriptions.4 | ||||||
| GET | /webhook_subscriptions | List the webhook subscriptions for a user or an organization. | read | webhooks:read | Current | |
Read-only. Acts onwebhook subscription Permission (capability) webhooks:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /webhook_subscriptions | Create a webhook subscription for chosen events at a user or organization scope. | write | webhooks:write | Current | |
Webhooks require the Calendly account to be on a paid Standard, Teams, or Enterprise plan. Acts onwebhook subscription Permission (capability) webhooks:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /webhook_subscriptions/{uuid} | Get a single webhook subscription. | read | webhooks:read | Current | |
Read-only. Acts onwebhook subscription Permission (capability) webhooks:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /webhook_subscriptions/{uuid} | Delete a webhook subscription so it stops receiving events. | write | webhooks:write | Current | |
Stops delivery to the registered URL. Acts onwebhook subscription Permission (capability) webhooks:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Data complianceDelete the stored data for one or more invitees.1 | ||||||
| POST | /data_compliance/deletion/invitees | Delete the stored data for one or more invitees, for data compliance. | write | data_compliance:write | Current | |
Permanently removes invitee data; an Enterprise-tier endpoint. Acts oninvitee Permission (capability) data_compliance:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Calendly can notify an app when something happens, like a meeting being booked or canceled, by posting an event to a webhook URL. A subscription is created through the API and scoped to a user or the whole organization, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
invitee.created | Fires when an invitee schedules a meeting, including a rescheduled booking. The payload carries the full invitee object: name, email, timezone, event URI, answers to custom questions, and tracking parameters. | /invitees |
invitee.canceled | Fires when a scheduled event is canceled by the host or the invitee, and also for the old booking during a reschedule. The payload includes the cancellation details and who initiated it. | /scheduled_events/{uuid}/cancellation |
routing_form_submission.created | Fires when someone submits a routing form, whether or not they go on to book. The payload includes the form questions, the answers, and a reference to any resulting booking. | In-app only |
Calendly limits how fast an app can call, by a per-token request rate measured each minute, and returns a 429 with a Retry-After header when the rate is exceeded.
Calendly meters requests per access token, by a per-minute rate rather than a per-method cost. Free, Standard, and Teams plans allow 60 requests per minute per token, and Enterprise plans allow 120 per minute. Each response reports the current state in the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Going over returns HTTP 429 with a Retry-After header that says how long to wait before retrying.
List endpoints are cursor-based. The count parameter sets the page size, defaulting to 20 and capping at 100, and the response's pagination object returns a next_page_token. The token is passed back as page_token to fetch the following page, rather than building the URL by hand. The availability endpoints take a date range instead, capped at 7 days per request.
A list page returns at most 100 records, the maximum value of count. A single-use scheduling link that is never used expires after 90 days. Requests and responses are JSON.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Invalid Argument | The request was malformed or a parameter was invalid. The body carries a title, a message, and a details array naming each bad parameter. | Read the details array, fix the named parameters, and resend. |
| 401 | Unauthenticated | The access token is missing, invalid, or expired. A token is revoked when the account's login email, password, or login method changes. | Send a valid Bearer token, and refresh an expired OAuth token before retrying. |
| 403 | Permission Denied | The token is valid but lacks permission for the resource, for example a missing scope or an endpoint limited to organization admins or to Enterprise plans. | Request the missing scope, or use a token whose user has the required role or plan. |
| 404 | Not Found | The resource does not exist or is not visible to this token. | Confirm the resource URI and that the token's user can reach it. |
| 429 | Too Many Requests | The per-token request rate was exceeded. The response carries a Retry-After header. | Wait for the Retry-After interval, then retry with backoff and a smoother request rate. |
| 500 | Internal Server Error | An unexpected error on Calendly's side prevented the request from completing. | Retry with backoff, and contact Calendly support if it persists. |
Calendly runs a single, continuously updated version of its v2 API rather than dated versions, and ships new capabilities through developer announcements, like the Scheduling API and scoped permissions.
Calendly's v2 API is a single, continuously updated REST API at https://api.calendly.com with no dated version header. New capabilities ship additively through developer announcements rather than versioned releases, so there is no breaking-change version to pin.
The Scheduling API became generally available, adding a Create Event Invitee endpoint that books a Calendly meeting by API with no redirect, iframe, or Calendly-hosted UI. The Calendly account must be on a paid plan to use it.
Calendly announced the upcoming Scheduling API and its Create Event Invitee endpoint, enabling programmatic scheduling of meetings on behalf of invitees, ahead of the October general availability.
There is no version header to pin; new endpoints and scopes are additive.
Calendly developer announcements ↗Bollard AI sits between a team's AI agents and Calendly. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.