Calendly API Guide 2026: Tokens, Webhooks, Scheduling API and MCP

What the Calendly API lets you build

The Calendly API lets your software read and change what happens in Calendly: event types, availability, scheduled meetings, invitees, contacts and Notetaker recaps. Calendly actually offers three APIs. API v2 handles data, the Embed API puts booking pages on websites, and the Webhook API sends data whenever invitees schedule or cancel. Since 2026 an MCP server sits beside them for AI assistants. This guide covers API v2, the only version still running. The short version: you can read almost anything on any plan, but booking and real-time events cost money.

Which plan you need

The REST API is open to every plan, and developers can make GET and POST requests on behalf of a Calendly user on any subscription ^[1]. Webhooks and the Scheduling API, however, need a paid plan. For a solo developer, the step from Free to Standard brings a tenfold rate limit plus webhooks and the Scheduling API, all for $120 a year on annual billing. A few endpoints are reserved for Enterprise: listing activity log entries, listing outgoing SMS and email communications, deleting invitee data and deleting scheduled event data. Data deletion requests can take up to 7 days to complete. Plan compliance tooling accordingly.

Authentication: tokens, OAuth and scopes

Personal access tokens or OAuth

Calendly's rule is simple: OAuth is required for multiple accounts, while personal access tokens are for a single account. Tokens suit internal tools. You create one inside your normal Calendly account under Integrations, then API and Webhooks, and choose its scopes at creation. Copy it immediately, because Calendly does not display or store it afterward, and never reuse it across applications. A token generated by an admin or owner can reach organization data, while a regular user's token sees only that user's data. Changing your login email or password revokes tokens.

OAuth apps, needed for public apps used by many Calendly customers, live in a separate developer account. That account is not your Calendly account; you sign up with GitHub or Google. Calendly recommends starting with Sandbox for development and creating a second application for Production. Copy the client secret and webhook signing key at creation, because you cannot see them again. PKCE is mandatory for mobile and native apps and recommended, though not enforced, for web apps. Use it everywhere.

Access and refresh tokens

OAuth access tokens expire after two hours, and refresh tokens last until used. The token endpoint allows only 8 tokens per user within one minute, so cache access tokens and refresh only when they expire. An app that refreshed on every request would hit that limit after eight calls, while one that caches a two-hour token needs at most twelve refreshes a day per user, by our arithmetic.

Refresh tokens are now single use, and reusing one fails with HTTP 400 or 401 and an invalid_grant error ^[2]. The deadline for older apps was August 31, 2026. Store the new refresh token from every response. In practice, a background job and a web server sharing one refresh token will break after the first refresh. The second process presents a token that is already spent.

Scopes

Since March 3, 2026, API access uses authorization scopes. New OAuth apps and new personal access tokens get no API access until scopes are explicitly requested, and users can decline them. Request only what you need, because broad scopes add friction at install. An integration that only syncs bookings into a CRM needs read access to scheduled events and webhooks, not write access to users or organizations. Legacy apps and tokens issued before scopes keep full access, and a legacy token migrates to the scoped format when it is refreshed. Existing installs may need reauthorization to add scopes later.

Reading your scheduling data

URIs, not IDs

Calendly identifies resources by full URI rather than by ID, and any parameter that references a resource has to be a URI. Store the whole URI for users, event types and events, not the trailing ID. Start by calling the current user endpoint with your token as a Bearer token in the Authorization header. The response includes your user URI and your organization URI, and every later list call needs one of them as a filter. With OAuth, both arrive in the access token payload. Keep the organization URI in configuration.

Event types and availability

You can list event types for a user or organization and filter out admin-managed ones. Since June 4, 2025, the API can also create and update event types, though only one-on-one types, with at most four duration options. New event types are created inactive by default, so activate them after setup. Listing has also been able to filter by active or inactive status since February 2022.

The available times endpoint has covered 31 days per request since July 9, 2026, up from 7. A month used to take five requests; now it takes one. The start must be in the future. Busy times, by contrast, are limited to seven days per request, and external events appear only for calendars set to check for conflicts. A month of busy time for 20 users needs about 100 calls. You can also read availability schedules and date overrides and update an event type's availability with PATCH.

Scheduled events and invitees

List scheduled events for a user, a group or an organization. The user filter alone works only for your own events, and group filtering needs organization admin, owner or group admin rights. Each event has invitees, carrying answers, UTM data, payment details, and cancel and reschedule URLs. Webhook payloads do not expose every invitee detail, so call Get Event Invitee for the full record.

Booking and changing meetings

The Scheduling API, launched October 15, 2025, books an invitee directly from your app without a redirect ^[3]. Bookings behave as if made in Calendly, with the standard notifications, calendar invites, reschedules and workflows. A team can build its own booking flow without rebuilding reminders or CRM sync. The endpoint is limited to paid plans, Standard and above, and Free users get a 403. The start time must be an open slot, in UTC. Location is required unless the event type has none, but for round robin event types you must not pass it.

Canceling works through a POST to the cancellation endpoint, with an optional reason. It cancels a whole event, including a group event, but cannot remove one invitee from a group. Rescheduling is the gap: "At this time, there is no API endpoint that supports rescheduling an event or invitee". Send the invitee the reschedule URL from the invitee resource or the webhook payload instead. No-shows can be marked and undone through the API, which is handy for syncing them from a CRM or call system. In the interface, a marked no-show stops thank-you and follow-up automations for that invitee.

Three link tools round this out. Single-use links, created with max_event_count set to 1, suit personalized outreach and expire after 90 days if unused. Shares customize an event type for one invitee without a new event type, copying any parameter you leave out, and work for one-on-one types only. One-off event types set a host, optional co-hosts, a duration and a date for ad hoc meetings, with no permanent event type left behind.

Organizations, contacts and Notetaker data

The organization endpoints list members, invite users, revoke invitations and remove users; removing someone requires admin rights, and the owner cannot be removed. Groups, added in May 2024 with their own OAuth scope, represent groupings of users within an organization. One person can be admin of several groups but a member of only one. The routing forms API lists forms and submissions. Its webhook fires on every submission, booked or not, which makes form-to-booking drop-offs visible.

The Contacts API launched on May 27, 2026, for two-way sync with CRMs, marketing tools, workflow engines and AI assistants. It gets, lists, creates, updates and deletes contacts. Watch one trap: "Updating emails will overwrite all existing emails for the contact". A sync job must read each contact before updating its emails. Since August 25, 2026, the API also reads and writes custom field values, using merge semantics, so send only the fields you change. Writes to an unknown or retired field are rejected, and no new scopes are needed.

The Notetaker API, launched July 22, 2026, lists recaps, returns transcripts and updates or deletes recaps, but cannot create them. It requires a paid plan. Recaps from external meetings have a null event field. Because nothing can be created through the API, the source of truth and the recording consent stay with the host inside Calendly.

Webhooks: real-time events without polling

Webhooks push events to your server so you do not have to poll. They cover invitee created and canceled, no-shows, event types, routing form submissions, contacts and meeting recaps. Subscriptions need a paid plan and the related read scopes, such as contacts:read or meeting_recaps:read, and can be scoped to an organization, a user or a group. Listing subscriptions always requires the organization parameter. Test your handler with the sample data endpoint before going live. To pass your own data into a booking, add UTM parameters to the scheduling link; they stay hidden from the booking flow and come back in webhooks.

Signatures, retries and timeouts

Verify that payloads come from Calendly. OAuth apps get a webhook signing key automatically, and with personal access tokens you set one when creating the subscription. Return a 2xx fast. On failure, Calendly keeps retrying for 24 hours with back-off, then disables the webhook until you recreate it. The connection timeout is 10 seconds and the read timeout 15. Queue the work and acknowledge at once. An endpoint that goes down on Friday night loses its subscription on Saturday, and every booking after that is missed until someone recreates it.

Reschedules and people who leave

A reschedule fires invitee.canceled with rescheduled set to true, plus a new invitee.created. Old and new references live on the invitee, so match records by invitee URI. Ownership matters too. Organization-scoped webhooks created by an admin keep working after that admin leaves, but user-scoped webhooks stop when their creator is removed. Create production webhooks at organization scope from a service admin account. For a company of 200 users, one such webhook replaces 200 user-scoped subscriptions and survives staff turnover.

Rate limits and errors

Limits are per user: 500 requests per minute on paid plans and 50 on Free ^[4]. They apply both to direct calls and to calls made through third-party integrations, and they have been enforced on all public endpoints since September 20, 2023. Exceeding them returns HTTP 429 with rate limit headers. At 500 a minute, a nightly sync of 20,000 events fetched in pages of 100 needs only 200 calls, so most reporting jobs never come close.

Booking has its own limits since April 15, 2026. Trials get five requests per user per day; paid plans below Enterprise get 10 a minute, 50 an hour and 100 a day; Enterprise gets 500 a minute. At 100 a day, a booking agent tied to one rep can create about 3,000 meetings a month, which caps shared service accounts. High-volume booking needs Enterprise. Errors use standard HTTP codes: 400 for bad input, 401 for bad credentials, 403 for missing permissions or plan, 404 for missing resources and 429 for rate limits. Log the error body. It names the field at fault.

The Embed API and the MCP servers

The embed adds a booking page to any site with a snippet of HTML, in inline, popup or button styles; get the code from the event type's Add to Website option. A JavaScript call can create an inline embed on demand, once your data is ready. The embedded page notifies the parent window of key moments, such as an event type viewed, a time selected or an event scheduled, so you can fire analytics or change your app's state. You can prefill name, email and up to ten custom answers, which cuts form steps for logged-in users. Our Calendly embed guide covers the setup side.

Calendly's MCP server, launched for developers on March 11, 2026, turns natural language into Calendly API calls. It is hosted by Calendly and cannot be self-hosted. It uses OAuth with dynamic client registration and PKCE, issues no client secret and refuses personal access tokens, so an assistant that only accepts pasted API keys cannot connect. Only two scopes exist, mcp:scheduling:read and mcp:scheduling:write. Booking through MCP needs a paid plan, routing form tools need Teams or higher, and there is no reschedule, Contacts or Notetaker tool yet. For coding assistants, a separate docs MCP server exists, and the raw OpenAPI 3.1 specification is available as JSON and YAML.

Migrating from v1, and what changed since

API v1 is gone. Calendly announced its retirement on March 26, 2025, and the migration guide says v1 was retired as of August 27, 2025. API v2 does not match the v1 payload. Internal tools can switch to a personal access token; public apps must use OAuth. Any old Zapier step, script or plugin not updated since 2024 should be tested before it is trusted again. The developer changelog marks the milestones:

Three common builds, and the mistakes to avoid

For a CRM sync, subscribe to invitee created and canceled at organization scope, create or update records from each payload, and tag the source with UTM parameters; native Salesforce and HubSpot integrations may make custom code unnecessary. For reporting, Calendly recommends webhooks because they need no further input once created, and owners and admins can also pull the whole organization's events with a personal access token. Load both into your warehouse for no-show and conversion analysis.

For an AI booking agent, the Scheduling API supports booking inside a chat, workflow or copilot without a redirect, and booking for other users needs an OAuth app. Off-the-shelf assistants are simpler with MCP. Before writing any code, check our Calendly integrations guide, since a native connector may already do the job. When you do build, most failures come from five documented, avoidable mistakes:

• Storing IDs instead of URIs.
• Reusing refresh tokens.
• Requesting available times beyond 31 days.
• Forgetting that webhooks need a paid plan.
• Letting a webhook endpoint fail for 24 hours until it is disabled.

The bottom line

The Calendly API is open on every plan for reading data, which makes small internal tools nearly free to build. Real integrations need Standard, because webhooks and the Scheduling API sit behind a paid plan, and high-volume booking needs Enterprise. Use a personal access token for internal tools and OAuth for public apps, request minimal scopes, store URIs, verify signing keys and create webhooks at organization scope from a service admin. Plan around the missing reschedule endpoint from day one.