calendly-scheduling-core-openapi

Getting credentials

1. Create or sign in to a Calendly account at Calendly.
2. For personal testing, create a Calendly personal access token if available for your account. For a multi-user integration, configure Calendly OAuth 2.0 through the Calendly Developer Portal.
3. Grant only the scopes required by the workflow. Read-only workflows need read access; direct booking requires the scheduled_events:write scope.
4. When VX Agent asks for authentication, provide the Calendly access token using Bearer authentication.

Keep the token private. Do not paste it into the Swagger file, marketplace description, prompts, or chat messages.

How to use this API

Use the Calendly API to discover event types, find available meeting times, list scheduled events and invitees, book meetings, and cancel scheduled events.

A typical workflow is:

1. Use GET /users/me to verify the connected Calendly user and organization.
2. Use GET /event_types to find active event types and their canonical URIs.
3. Use GET /event_type_available_times with an event type URI and a UTC start and end time to find available slots.
4. Present the available times to the user in the correct local timezone and confirm the selected slot.
5. Use POST /invitees to book a meeting directly only when the account has the required scheduled_events:write scope and an eligible paid plan.
6. Use GET /scheduled_events to list upcoming or historical meetings.
7. Use GET /scheduled_events/{event_uuid} and GET /scheduled_events/{event_uuid}/invitees to inspect a specific meeting and its invitees.
8. Use POST /scheduled_events/{event_uuid}/cancellation only after the user explicitly confirms the exact event and cancellation reason.

Booking guidance

Before booking, verify the event type, date, UTC start time, invitee name, invitee email, timezone, guests, location, reminders, and required questions. A direct booking may trigger calendar invitations, reminders, notifications, and other Calendly workflows.

The POST /invitees operation may be unavailable on free plans or without the required permission. If direct booking is unavailable, use the availability and event-listing operations or provide the user's Calendly scheduling URL.

Use a limited availability window, such as the next 7 to 14 days. Do not use example event type URIs, placeholder email addresses, or fake event IDs in real requests.

Safety and privacy

Booking and canceling meetings affect real people and calendars. Always ask for confirmation immediately before booking, adding guests, sending reminders, or canceling an event. Confirm the final time, timezone, invitee email, event type, and cancellation reason.

Only access event types, events, and invitees authorized by the connected Calendly user. Treat invitee names, email addresses, phone numbers, meeting locations, and notes as personal information. Do not expose access tokens or private scheduling data.

Troubleshooting

A 401 response usually indicates an invalid or expired Bearer token. A 403 response may indicate a missing scope, insufficient organization permission, or an account plan that does not support direct booking. A 400 response may indicate an invalid event type URI, unavailable time, timezone error, missing invitee field, or invalid question answer.

Official documentation: Calendly API Documentation and Create Event Invitee.