Calendly | Smallest AI Docs

Connect Calendly so your agent can check your availability, book the caller in and look up the meetings they already have.

At a glance


Authentication	Calendly personal access token
Asked at connect	Your token
Books into	One default event type, picked when you connect
Plan	Every tool works on any plan. On the free plan, Book meeting is limited to 5 bookings per user per day
Works with	Single-prompt agents

Connect Calendly

Create a personal access token

Sign in at calendly.com and open the profile menu → Developer → Personal access tokens (on older accounts: Integrations → API & Webhooks), then create a personal access token.

New tokens have no API access until you choose scopes. Select these:

Scope	Used for
`users:read`	Get calendar owner, picking your default event type
`event_types:read`	Listing and reading event types, Check availability
`scheduled_events:read`	Listing and reading events
`scheduled_events:write`	Book meeting, Cancel meeting

Copy the token straight away. Calendly doesn’t show it again.

Paste it on the Integrations page

Open the Integrations page in the dashboard, click Connect next to Calendly, paste the token into API key, and click Connect.

The token is checked against your account straight away and stored encrypted. It’s never shown again.

Add the tools to your agent

Click Go to Tools, then Add tool → Integration tool, choose Calendly, tick the tools this agent needs, and click Add tools. From inside an agent, use Add tool → New tool → Integration tool instead.

Which event type the agent books

When you connect, your active event type whose length is closest to 30 minutes becomes the default. The agent books that event type, with its duration, name and location settings.

The default is chosen once, at connect. If you change your event types in Calendly later, disconnect and connect again.

Tools

Tool	Function name	What it does
Check availability	`calendly_check_availability`	Returns available start times in a window
Book meeting	`calendly_book_meeting`	Books the caller into the default event type
Cancel meeting	`calendly_cancel_meeting`	Cancels a scheduled event
List events by invitee	`calendly_list_events_by_invitee`	Finds a caller’s meetings by email
List events	`calendly_list_events`	Lists scheduled events with filters
Get event	`calendly_get_event`	Reads one scheduled event
Get calendar owner	`calendly_get_owner`	Returns the connected user and their URIs
List event types	`calendly_list_event_types`	Lists your event types
Get event type	`calendly_get_event_type`	Reads one event type

Calendly has no reschedule API. To move a meeting, the agent cancels it and books a new one. The invitee receives a cancellation and a new booking, not a “rescheduled” email.

Fields

Check availability

Field	Required	Description	Pinnable
`start_time`	Yes	Start of the window. Local date and time in `timezone`, no UTC offset (for example `2026-09-01T09:00:00`)	Yes
`end_time`	Yes	End of the window, in the same form
`timezone`	Yes	IANA timezone, for example `America/New_York`
`event_type_uri`	No	Check a different event type	Yes

Book meeting always books the default event type. Leave event_type_uri empty so the agent doesn’t offer times from one event type and book another.

Book meeting

Field	Required	Description	Pinnable
`start_time`	Yes	A time returned by Check availability
`timezone`	Yes	The invitee’s IANA timezone	Yes
`attendee_email`	Yes	Where the confirmation goes	Yes
`attendee_name`	Yes, or first name	Full name	Yes
`attendee_first_name` / `attendee_last_name`	No	Instead of a full name	Yes
`location_kind` / `location`	If the event type has a location	Must match the event type’s location, for example `google_conference`, `physical` with an address, or `outbound_call` with the invitee’s number. Pin `location_kind` to your event type’s kind	Yes
`questions_and_answers`	No	Answers to the event type’s questions, as a JSON array
`event_guests`	No	Comma-separated guest emails, up to 10	Yes
`utm_campaign`, `utm_source`, `utm_medium`, `utm_content`, `utm_term`	No	Tracking tags on the booking	Yes
`salesforce_uuid`	No	A Salesforce record ID to attach	Yes

The meeting name comes from the event type.

Cancel meeting

Field	Required	Description	Pinnable
`booking_uid`	Yes	The scheduled event’s URI, from List events by invitee
`reason`	No	Why it’s being cancelled	Yes

List events · List events by invitee · List event types

Each needs a user or organization URI (the two list-events tools also accept a group URI). Pin it: call Get calendar owner once, or copy it from Calendly, and set user to Fixed, so the agent never has to look it up.

Field	Tools	Description
`invitee_email`	Both list-events tools (required for by invitee)	The caller’s email
`status`	Both list-events tools	`active` or `canceled`
`min_start_time` / `max_start_time`	List events	Time range
`count`	All	1–100. Defaults to 20
`sort`	All	`start_time:asc` or `start_time:desc` for events; `name`, `position`, `created_at` or `updated_at` for event types, for example `name:asc`
`active`	List event types	Active only. Defaults to `true`

Pin the values that never change

Field	Typical pin	Why
`user`	`https://api.calendly.com/users/…`	List tools work without an extra lookup
`timezone` (Book meeting)	`America/Chicago`	Bookings are created in your zone
`utm_source` / `utm_medium`	`voice-agent` / `phone`	You can filter and export the agent’s bookings by tracking tags in Calendly
`reason` (cancel)	`Cancelled by caller over the phone`	The reason is recorded with the cancellation

Limits

The agent books only the default event type.
On the free Calendly plan, Book meeting is limited to 5 bookings per user per day. Over the limit, the agent is told “Provider rate limit reached — retry shortly”.
One Calendly account per organization. To switch to a different one, click Disconnect, then Connect again.

Troubleshooting

Calls fail with 'Calendly rejected the credential'

Calendly refused the request. There are two usual causes:

A token without the scopes above.
A revoked token.

Reconnecting with the same token won’t help. Create a new token with the right scopes, then click Disconnect and Connect with it.

'Invalid Calendly API key' when connecting

The token is wrong, revoked, or missing the users:read or event_types:read scope. Create a new token with the scopes above and connect again. If you see ‘Could not reach Calendly to validate the key’, try again in a minute.

'No event types found on this Calendly account'

Create an active event type at calendly.com/event_types, then connect again.

'user or organization is required' or 'user, organization, or group is required'

Pin the user field on the list tools to your Calendly user URI.

Integrations overview

Connecting, pinning fields and disconnecting

Cal.com

The same flow for Cal.com