What we do
Tools
Industries
Department
How we workLet's talk →
Home/Calendly/Calendly API v2
Calendly API

The Calendly API: making a booking start the work that follows it

Calendly's v2 REST API reads and writes event types, scheduled events, invitees and availability, and can now book a meeting directly. Webhook subscriptions tell your system the moment someone books, cancels or reschedules, so nothing has to poll. Below: the token to use, your first subscription, and what each plan lets your code do.

If an old Calendly integration just stopped

Calendly retired the v1 API and v1 webhooks on August 27, 2025, and they're no longer available. Anything still sending the old API key from the integrations page now fails.

The fix is to move to v2 with one of two kinds of credential. A personal access token suits your own account or an internal tool. OAuth is for an app that other Calendly users connect to their own accounts. Webhook subscriptions have to be recreated on v2 as well.

Your first Calendly webhook subscription

  1. 1

    Create a personal access token

    Profile menu Developer Personal access tokens

    Name it after the integration that'll use it. If you don't see Developer yet, tokens are still managed from the Integrations page on your account.

  2. 2

    Find your user and organization

    Call GET https://api.calendly.com/users/me with the header Authorization: Bearer <token>. The response gives your user URI and your current organization URI. You'll need both.

  3. 3

    Create the subscription

    POST /webhook_subscriptions with your url, the events (for bookings: invitee.created and invitee.canceled), the organization, and a scope of user, organization or group. Include a signing_key of your own.

    Watch for: the user scope covers your own bookings. To catch every booking across the team, use organization scope.

  4. 4

    Verify each delivery

    Calendly signs every webhook with your key. The Calendly-Webhook-Signature header holds t= (a timestamp) and v1= (an HMAC-SHA256 of the timestamp, a period and the raw body). Recompute it, compare, and reject old timestamps so a captured request can't be replayed.

What catches Calendly webhook receivers out

A reschedule looks like a cancellation

How you'll know: A client moves their call and your system marks them as lost, then creates a second record for the new time.

Fix: A reschedule sends both invitee.canceled and invitee.created. The canceled payload has rescheduled set to true, and the new invitee carries a link to the old one. Check those before treating it as a cancellation or a brand-new booking.

History only starts from the day you subscribed

How you'll know: The new CRM shows this week's bookings and nothing before.

Fix: Webhooks only fire going forward. Pull past scheduled events and their invitees through the API once, then let the subscription carry on from there.

Every booking treated the same

How you'll know: Existing clients get the new-lead email, and a cancellation creates a duplicate instead of updating the record.

Fix: Look the invitee's email up in your own system before acting, and branch: update the client, create the lead, or close the meeting on the record.

Custom question answers in the wrong field

How you'll know: Intake answers end up as one blob of text in a notes field.

Fix: The invitee payload carries each question with its answer. Map them by question to the fields your team actually works from.

What your code can do on each Calendly plan

If your account is on You get Watch for
The free plan The v2 API at 50 requests a minute per user, and most webhook events, including bookings and cancellations. Booking meetings through the API is capped at 5 a day. Routing form, contact and meeting recap events need a paid plan.
A paid plan 500 requests a minute per user, and the webhook events tied to the features your plan includes. Booking through the API is capped at 10 a minute, 50 an hour and 100 a day outside Enterprise.
Enterprise The same API, with booking through the API raised to 500 a minute. The organization owner's plan decides which webhook events are allowed. A 403 saying "Please upgrade" means the event isn't on it.

Where a single Zapier step runs out

Calendly's Zapier and Make integrations cover one trigger and one action well. These are the jobs that need more.

01

Logic that branches on who booked

An existing client and a new lead get different records, different owners and different follow-ups. n-frames builds the receiver that checks first and then acts, which one trigger-action step can't do alone.

02

Past bookings pulled in, not just new ones

When a business switches CRMs or starts automating for the first time, months of past Calendly events come across through the API in one pass, so the new system doesn't start blank.

03

Bookings made from your own app

The API's create-invitee endpoint books a meeting without the Calendly page, and Calendly still sends the usual invites and reminders. Useful inside a client portal, within the per-plan limits above.

Questions people ask

Is the Calendly API free to use?

Yes, the v2 API works on the free plan, at 50 requests a minute per user against 500 on paid plans, and most webhook events, including new bookings and cancellations, are available on every plan. Routing form submissions, contacts and meeting recaps need a paid plan, and booking through the API is capped at 5 a day on free.

What are Calendly webhooks?

Notifications Calendly sends to a URL you choose when something happens: a booking, a cancellation, a no-show being marked, an event type changing. Each one carries the event and invitee details, so your system doesn't have to keep checking Calendly for changes.

Does Calendly have an official SDK?

Calendly's developer docs don't list official client libraries for each language. They publish the API as plain REST endpoints with an OpenAPI spec, so most integrations call it directly or generate a client from that spec.

What is calendly MCP?

Calendly hosts an official MCP (Model Context Protocol) server at mcp.calendly.com. It lets an AI assistant list event types, find open times, book or cancel meetings and create one-time links, using the same v2 API. It signs in with OAuth, not a personal access token.

Do I need a developer to use the Calendly API?

For anything beyond a single trigger and action, yes: someone has to write and host the code that receives webhooks and calls the API. Zapier or Make can cover the simplest one-step automations without one, and n-frames builds the rest.

Should I use a personal access token or OAuth for Calendly?

A personal access token for your own account or an internal tool. OAuth when you're building something other Calendly users connect to their own accounts, like an app other businesses install.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.