---- url: https://developer.calendly.com/get-help ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) How Can We Help You? Contact Support The Calendly team is here to help. Tell us about your problem, and we’ll find you a solution. [support+developer@calendly.com](mailto:support+developer@calendly.com) [Help Us Improve: Share Your Feedback Today](https://docs.google.com/forms/d/1ZYnoQ7XUbnaUnfB204WWXnqTjXR6KDce76FuyC0rZLQ/edit) How will you connect with Calendly? [See all the possibilities](/api-docs) [API](/api-docs/YXBpOjM5NQ-calendly-api) View all API objects, methods, attributes and responses [Learn more](/api-docs/YXBpOjM5NQ-calendly-api) [Webhook](/api-docs/b3A6NTkxNDI1-create-webhook-subscription) Listen for scheduled meeting events and trigger follow up actions [Learn more](/api-docs/b3A6NTkxNDI1-create-webhook-subscription) [Embed](/api-docs/ZG9jOjI3ODM2MTAy-getting-started) Embed Calendly within your application in more than one ways [Learn more](/api-docs/ZG9jOjI3ODM2MTAy-getting-started) --- ---- url: https://developer.calendly.com/supported-tools ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Supported Tools Documentation/Calendly MCP Server Calendly MCP: Supported Tools ============================= Below is the complete list of tools exposed by the Calendly MCP server, organized by category with the equivalent REST endpoint for each. For setup, authentication, and integration details, refer to the full [Calendly MCP Server documentation](/calendly-mcp-server). Category Tool Name Description Equivalent Endpoint Scheduling event_types-create_event_type Create a new event type POST /event_types event_types-update_event_type Update event type details PATCH /event_types/{uuid} event_types-list_event_types List event types for a user/org GET /event_types event_types-get_event_type Retrieve event type details GET /event_types/{uuid} event_types-list_event_type_available_times List available time slots GET /event_type_available_times event_types-list_event_type_availability_schedules List availability schedules GET /event_types/{uuid}/availability_schedules event_types-update_event_type_availability_schedule Update an availability schedule PUT /event_types/{uuid}/availability_schedule locations-list_user_meeting_locations List a user’s meeting locations GET /user_meeting_locations scheduled_events-list_events List scheduled events GET /scheduled_events scheduled_events-get_event Retrieve event details GET /scheduled_events/{uuid} scheduled_events-cancel_event Cancel a scheduled event POST /scheduled_events/{uuid}/cancellation scheduled_events-create_event_invitee Create a new booking (Scheduling API) \*Requires a paid Calendly plan POST /invitees scheduled_events-list_event_invitees List invitees for an event GET /scheduled_events/{uuid}/invitees scheduled_events-get_event_invitee Get invitee details GET /scheduled_events/{uuid}/invitees/{invitee_uuid} scheduling_links-create_scheduling_link Create a single-use scheduling link from an existing event type without any customization. POST /scheduling_links shares-create_share Create and customize a single-use scheduling link from an existing event type. POST /share availability-list_user_availability_schedules List user availability schedules GET /user_availability_schedules availability-get_user_availability_schedule Get a schedule’s details GET /user_availability_schedules/{uuid} availability-list_user_busy_times List busy times within a range GET /user_busy_times scheduled_events-create_invitee_no_show Mark invitee as no-show POST /invitee_no_shows scheduled_events-get_invitee_no_show Get no-show details GET /invitee_no_shows/{uuid} scheduled_events-delete_invitee_no_show Remove no-show status DELETE /invitee_no_shows/{uuid} routing_forms-list_routing_forms List routing forms \*Requires a Calendly Teams plan or higher GET /routing_forms routing_forms-get_routing_form Get form details \*Requires a Calendly Teams plan or higher GET /routing_forms/{uuid} routing_forms-list_routing_form_submissions List form submissions \*Requires a Calendly Teams plan or higher GET /routing_forms/{uuid}/submissions routing_forms-get_routing_form_submission Retrieve a submission \*Requires a Calendly Teams plan or higher GET /routing_form_submissions/{uuid} User & Org Management users-get_current_user Get the authenticated user GET /users/me users-get_user Get a specific user by UUID GET /users/{uuid} organizations-get_organization Retrieve org details GET /organizations/{uuid} organizations-list_organization_memberships List organization members GET /organization_memberships organizations-get_organization_membership Get membership details GET /organization_memberships/{uuid} organizations-delete_organization_membership Remove a member DELETE /organization_memberships/{uuid} organizations-list_organization_invitations List pending invitations GET /organizations/{uuid}/invitations organizations-create_organization_invitation Invite a user POST /organizations/{uuid}/invitations organizations-revoke_organization_invitation Revoke an invitation DELETE /organizations/{uuid}/invitations/{invitation_uuid} --- ---- url: https://developer.calendly.com/displaying-availability-of-users ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Displaying the Availability of Your Users Displaying the Availability of Your Users ========================================= In this guide, we'll explore two effective methods of displaying your user’s availability: using a table or utilizing a calendar view. With this ability you are able to see how many available time slots are open and track number of bookings against overall availability. You can then take appropriate actions if time slots are limited. Each approach offers its own benefits. --- Please note that some prior JavaScript and/or React knowledge will be needed to implement these. --- Using a table to display the availability and busy times of your users --- There are many possible implementations of the above table. This example uses the GET `/user_availability_schedules` and `/user_busy_times` endpoints to retrieve data and display it in a useful format.  - The “Day of Week” column pulls from the `rules` array returned in the `/user_availability_schedules` collection - The “Availability Range(s)” column is also populated from the `rules` array returned in the `/user_availability_schedules` - The “Unavailable Times” column pulls from the `/user_busy_times` endpoint - The “Total Scheduled Hours” column calculates the total booked time slots in a human-readable format, using [Moment.js](https://www.npmjs.com/package/moment?activeTab=readme)  - The “Total Available Hours To Book” column simply calculates the difference between column 2’s and column 4’s totals, while also making use of [Moment.js](https://www.npmjs.com/package/moment?activeTab=readme) Using a calendar to display the availability and busy times of your users --- Source: [https://www.npmjs.com/package/react-big-calendar](https://www.npmjs.com/package/react-big-calendar) Note: This gif does not show a direct example of integrating Calendly, rather what the generic react-big-calendar looks like INCLUDE BUZZWORD INFO As [Buzzword](https://github.com/calendly/buzzwordcrm) is built using React, we recommend [react-big-calendar](https://www.npmjs.com/package/react-big-calendar) (npm - not managed by Calendly) as an excellent choice for showcasing the rendering of [user busy times](/api-docs/5920076156501-list-user-busy-times) and [availability](/api-docs/8098de44af94c-list-user-availability-schedules) in a calendar format. You’ll want to manipulate the `events` array with your “available” and “busy” objects - For “available” times, you can create an object like: `{`        `start: moment({ hours: 22 }).toDate(),`        `end: moment({ hours: 23 }).toDate(),`        `title: "Available"` `}` - `For “busy” times, you can create an object like:` `{`        `start: moment({ hours: 13 }).toDate(),`        `end: moment({ hours: 14 }).toDate(),`        `title: "Unavailable"` `}` Things to note: - When handling a user's availability rule, it can be either for a specific date or a particular day of the week.  - To handle this, we suggest creating a separate object with weekday keys (e.g., Monday-Sunday) and corresponding start time and end time values.  - You can use this separate object to extract the necessary information and create your "available" object in the events array.  - The implementation approach for this is flexible and can be customized according to your requirements. - The user's collection of busy times consists of busy ranges represented by start and end times in UTC ISO-8601 format, organized by date.  - Once again, we suggest creating an additional object with weekday keys and corresponding start and end time values.  - This object can then be used to extract the necessary information and create the separate "busy" object in the events array.  - Again, the specific implementation details can be tailored to your preferences and requirements. - For an examples of the objects directly above, see `components/userBusyTimes.jsx` in the [Buzzword repo](https://github.com/calendly/buzzwordcrm) --- ---- url: https://developer.calendly.com/how-to-display-the-scheduling-page-for-users-of-your-app ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Embed Calendly How to display the scheduling page for users of your app ======================================================== You can display the scheduling page for users of your app when you initialize [one of three embed types](https://help.calendly.com/hc/en-us/articles/223147027?tab=general#embed-options-overview-0-0) based on information from the API such as the scheduling page link. To do this, you’ll need to [generate an OAuth or personal access token](/getting-started) for either public or private use, respectively. To display the landing page of a specific user --- 1. To display the current user’s landing page link, make a call [/users/me](/api-docs/b3A6MTEzMDIyOQ-get-current-user) to retrieve current user’s details. The landing page link can be found in the `scheduling_url` property. Proceed to step 4. 2. To retrieve a specific user’s landing page link in an organization, use a personal access token generated by an admin or owner, then make a call to [/organization_memberships](/api-docs/b3A6NTkxNDI0-list-organization-memberships) including the organization query parameter in your request to get a list of users in the organization. Each returned user will have a `scheduling_url` property which contains the landing page link. Proceed to step 4 3. To display the event scheduling page of a specific user, make a call to [/event_types](/api-docs/b3A6NTkxNDEz-list-user-s-event-types) to get a list of event types associated with a user or an organization. The event type’s link can be found in the `scheduling_url` property. Proceed to step 4 4. To use the link to initialize an embed, replace the `myLink` variable with the landing page link or event type link found in the `scheduling_url` property. 1. To initilize an inline embed, use `Calendly.initInlineWidget({url: myLink});` 2. To initialize a pop-up embed, use `Calendly.initPopupWidget({url: myLink});` 3. to intialize a pop-up widget embed, use `Calendly.initBadgeWidget({ url: myLink, text: 'Schedule time with me', color: '#006bff', textColor: '#ffffff', branding: true });` Note: The pop-up widget will require you to pass extra information when initializing the embed which define the floating button’s text and style. To pass UTM and pre-filled information to each embed type, see the [advanced embed options](https://help.calendly.com/hc/en-us/articles/223147027?tab=advanced) Help Center article. --- ---- url: https://developer.calendly.com/authentication ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Authentication Overview ======== While building apps on Calendly’s developer platform, you can configure authentication based on how you plan to install your app. App authentication --- There are two authentication types available based on how you plan to distribute your app: OAuth is required for multiple accounts, while personal access tokens are used for installing in a single account at a time. Personal access tokens --- If you need to securely share data from your or your company’s Calendly account with an internal or private application that’s not for use by others outside of your company, then use personal access tokens. They are unique and not meant to be shared with public sources or reused across applications. ### Use personal access tokens when you’re: - Testing out Calendly’s API endpoints in a local development environment - Building a reporting dashboard to reflect meetings your company has scheduled - Pushing Calendly event and invitee data into your company’s CRM ### To get started, see [Personal access tokens overview](/personal-access-tokens) OAuth 2.1 --- If you need to provide a way for Calendly members to securely share their Calendly account data with a public application you’ve built, then use OAuth 2.1. ### Use OAuth 2.1 when you’re authenticating: - An application that allows your customers to get easy access to their Calendly event type links to share as they respond to support tickets - An application that creates an agenda each time your customer’s clients schedule a meeting with them - An application that contacts your customer’s Calendly invitees ### To get started, see [Creating an OAuth app](/creating-an-oauth-app) --- ---- url: https://developer.calendly.com/when-to-choose-between-personal-access-tokens-and-oauth ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) When to choose between personal access tokens and OAuth When to choose between personal access tokens and OAuth 2.0 to authenticate requests ==================================================================================== Personal access tokens --- If you need to securely share data from your or your company’s Calendly account with an internal or private application that’s not for use by others outside of your company, then use personal access tokens. They are unique and not meant to be shared with public sources or reused across applications. ### Use personal access tokens when you’re: - Testing out Calendly’s API endpoints in a local development environment - Building a reporting dashboard to reflect meetings your company has scheduled - Pushing Calendly event and invitee data into your company’s CRM ### To get started, see [How to authenticate with personal access tokens](/how-to-authenticate-with-personal-access-tokens). OAuth 2.0 --- If you need to provide a way for Calendly members to securely share their Calendly account data with a public application you’ve built, then use OAuth 2.0. ### Use OAuth 2.0 when you’re authenticating: - An application that allows your customers to get easy access to their Calendly event type links to share as they respond to support tickets - An application that creates an agenda each time your customer’s clients schedule a meeting with them - An application that contacts your customer’s Calendly invitees ### To get started, see [Create a developer account](/create-a-developer-account). --- ---- url: https://developer.calendly.com/track-and-report-on-all-scheduled-events-across-your-organization ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Report on scheduled events Track and report on all scheduled events across your organization ================================================================= Avoid pivots in your business plan when you analyze and report on your teams' scheduled events --- Calendly owners and admins can report on scheduled events of teams across their organization when they generate and use a personal access token to authenticate requests they make to Calendly’s API. There are two ways to report on scheduled events: 1. Make POST requests to the Calendly API to receive basic event and invitee data in real time via a webhook subscription. This method is suggested because after the webhook subscription is created, there is no further input required. 2. Make periodic GET requests to the Calendly API from your system to retrieve current event information to update your system with data from scheduled events. The information received via either method will include UTM parameters, which help track the source of the booking. To learn more about using UTM parameters, see guide [how to track conversions](https://help.calendly.com/hc/en-us/articles/1500005575121) in our Help Center. What's next --- [](/receive-data-from-scheduled-events-in-real-time-with-webhook-subscriptions)[How to receive data from scheduled events in real-time with webhook subscriptions ](/receive-data-from-scheduled-events-in-real-time-with-webhook-subscriptions)[How to update your system with data from scheduled events ](/update-your-system-with-data-from-scheduled-events-admins-only) --- ---- url: https://developer.calendly.com/create-a-developer-account ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) How to authenticate Calendly API via OAuth Create a developer account and your first application ===================================================== Follow the procedure below to register and authenticate your public application with the Calendly API v2. Register your OAuth application --- - Sign up for a Calendly developer account using your Github or Google account by clicking the Sign Up button found in the top right corner of this page. Note: This is not your Calendly user account and is not associated with your Calendly user account. - Create a new OAuth application - Provide name of your application - Select the kind of application (web or native) - Select your environment that you want to associate your application - Sandbox - Production We recommend starting with Sandbox for development and creating a second application for Production when ready to go live with customer data. - Redirect URI:  - For the Sandbox environment, we allow HTTP with localhost domain. Example: [http://localhost:1234](http://localhost:1234/)  - For the Production environment, this must be HTTPS - For mobile or native applications use a specific redirect_uri, a Proof Key for Code Exchange (PKCE), and S256 for code_challenge_method. For more information on native and mobile authentication, see [this guide](https://oauth.net/2/pkce/). - Proceed into the next step to view/copy your Client Id, Client Secret and Webhook signing key. Be sure to copy these values as you will not be able to access the Client Secret or Webhook signing key again. Test your application --- 1. To initiate the OAuth authorization flow, redirect your user to [Get Authorization Code](/api-docs/b3A6NTkxNDA5-get-authorization-code) endpoint. 2. To retrieve the access token, make a POST request to [Get Access Token](/api-docs/b3A6NTkxNDA4-get-access-token) endpoint. 3. To test the access token, make a call to the [Get current user](/api-docs/b3A6MTEzMDIyOQ-get-current-user) endpoint. Edit your application --- --- Learn what else you can [accomplish with the Calendly API](/api-use-cases). For more information about conditions that result in an access token being revoked, please see our [Frequently Asked Questions](/frequently-asked-questions). --- ---- url: https://developer.calendly.com/developer-policy ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Developer Policy ================ Our goal is to have a great developer community where we build an integrated solution between two or more technology products that enables our customers to unlock more value and solve their business needs with ease and in the most secure way. ### Security At Calendly, we take the security of our customer’s data very seriously. For our Technology Partners, your operating system, networks and web services must be configured to securely operate and data must be stored within your system using strong encryption.  Developers are prohibited from: - Compromise security in any way; - Provide access to Calendly API in any fraudulent or unauthorized way, including bypassing or circumventing Calendly protocols and access controls; - Transmit any viruses or other code that may damage any system or Data; - Reverse engineer, disassemble, decompile, decode, adapt, or otherwise attempt to derive or gain access to any software component of the API, in whole or in part;  - Remove any proprietary notices from the API;  - Use the API in any manner or for any purpose that infringes, misappropriates, or otherwise violates any intellectual property right or other right of any person, or that violates any applicable law;  - Combine or integrate the API with any software, technology, services, or materials not authorized by Calendly;  - Design or permit your applications to disable, override, or otherwise interfere with any Calendly-implemented communications to end users, consent screens, user settings, alerts, warning, or the like;  - Use the API in any of your applications to replicate or attempt to replace the user experience of the Calendly Offering; or  - Attempt to cloak or conceal your identity or the identity of your applications when requesting authorization to use the API.  In addition, you will not use the API in connection with or to promote any products, services, or materials that constitute, promote, or are used primarily for the purpose of dealing in spyware, adware, or other malicious programs or code, counterfeit goods, items subject to U.S. embargo, unsolicited mass distribution of email ("spam"), multi-level marketing proposals, hate materials, hacking, surveillance, interception, or descrambling equipment, libelous, defamatory, obscene, pornographic, abusive, or otherwise offensive content, stolen products, and items used for theft, hazardous materials, or any illegal activities. ### Use of Data Use of customer data must be transparent by disclosing the collection, use and sharing of the data. You must limit your use of the data to the practices you disclose. All Developers must have an industry standard privacy policy in place that accurately describes the specifics of data usage and meets applicable legal and consent requirements.  Developers are prohibited from: - Sharing user data to external party unless otherwise agreed by the user and for following reasons: - To comply and in accordance with applicable laws and regulations - Part of a merger or acquisition - If necessary to improve the user experience and business needs  - Subcontracting any processing of the data to a third party sub-processor without the prior written consent. ###  User Experience Every application must meet the business need and respect user privacy and provide a good user experience. Application should adhere to Calendly brand guidelines. Developers are prohibited from: - Degrading or compromising performance of the services - Creating poor User experiences that do not add value to users - Displaying inappropriate communications through your application. - Neglecting appropriate customer assistance. Application must be complemented with instructions on how to connect Calendly and customer support information ### Data breach If data is breached, exposed, exploited, or otherwise compromised through your application or company, you must inform all affected users and Calendly immediately at support+developer@calendly.com --- ---- url: https://developer.calendly.com/trigger-automations-with-other-apps-when-invitees-schedule-or-cancel-events ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Automate your process Trigger automation with other apps when invitees schedule, cancel, or reschedule events ======================================================================================= Our webhook subscription will inform you when invitees book, cancel, or reschedule events. While the process is completely manual, you can use the values within the webhook payload to trigger follow up actions in the internal or custom-built apps you or your team use. If you want to trigger automations without any development work, [learn more about our integration with Zapier](https://help.calendly.com/hc/en-us/articles/235289507-Zapier), which connects Calendly to apps you use daily. - When an event is scheduled, the `invitee.created` webhook is triggered. - When an event is canceled, the `invitee.canceled` webhook is triggered. - When an event is rescheduled, both the `invitee.created` and `invitee.canceled` webhooks are triggered. To learn more about creating a webhook subscription, see [receive scheduled event data in real time with webhook subscriptions](/receive-data-from-scheduled-events-in-real-time-with-webhook-subscriptions). Webhook payload values --- To create your own follow up actions, use the values located within the webhook payload. Some that may be helpful include: ### The event value The `event` value identifies which payload was triggered as a result of the meeting being scheduled or canceled: - `"``event``": "``invitee.created``"` is triggered when an event is scheduled - `"``event``": "``invitee.canceled``"` is triggered when an event is canceled ### The status value The `status` value identifies if the invitee is attending or not attending the scheduled event - `"``status``": "``active``"` indicates that the invitee will attend the scheduled event - `"``status``": "``canceled``"` indicates that the invitee will not attend the scheduled event ### The canceled value The `canceled` value identifies if the event was canceled - `"``canceled``":` `false` indicates that the event has not been canceled - `"``canceled``": true` indicates that the event has been canceled - The `canceled_by` value identifies who, either the Calendly user or invitee, canceled the meeting - The `reason` value (if provided by the canceler) lists the textual response the canceler entered when canceling the event The rescheduled value --- The `rescheduled` value identifies if the event has been rescheduled - `"``rescheduled``":` `true` indicates the event has been rescheduled - `"``rescheduled``":` `false` indicates the event has not been rescheduled Working with webhooks to analyze data or trigger automation --- Put your data to work when you use these guides to receive, understand, and report on Calendly data when it arrives at an endpoint you specify. [How to track and report on all scheduled events across your organization](/track-and-report-on-all-scheduled-events-across-your-organization) [How to receive data from scheduled events in real-time with webhook subscriptions](/receive-data-from-scheduled-events-in-real-time-with-webhook-subscriptions) [How to understand webhook payloads when invitees reschedule events](/see-how-webhook-payloads-change-when-invitees-reschedule-events) --- ---- url: https://developer.calendly.com/receive-data-from-scheduled-events-in-real-time-with-webhook-subscriptions ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Create a Webhook Subscription Receive data from scheduled events in real time with webhook subscriptions ========================================================================== When you [create a webhook subscription](/api-docs/b3A6NTkxNDI1-create-webhook-subscription), payloads will be sent in real time to your server endpoint when events are scheduled or canceled by either the host or the invitee. When you create a webhook subscription, you can subscribe to either or both: - `invitee.created` for only data about scheduled events by invitees - `invitee.canceled` for only data about canceled events by invitees - `routing_form_submission.created` for only data about routing form submissions Subscribing to both `invitee.created` and `invitee.canceled` events will return all scheduled and canceled events across all team members in your organization with a single subscription giving you full transparency into the success of meetings. Subscribing to the `routing_form_submission.created` event will fire anytime someone submits a routing form, whether they book or not. NOTE: The only allowed subscription scope for Routing form submissions is `organization`. If you’re an owner or admin, the personal access token you generate will authenticate the POST request with: - the `user` scope if you want to return a response payload for data about all scheduled events for yourself - the `organization` scope if you want to return a response payload for data about all scheduled events for your organization If you’re a team member and not an owner of admin of a Calendly organization, the personal access token you generate will only authenticate the POST request with the `user` scope to return a response payload for data about your own scheduled events. To create a webhook subscription --- Before you create a webhook subscription, ensure that you have the `organization` or the `user` URI (see [how to find the organization or user uri](/how-to-find-the-organization-or-user-uri)) depending on which events you want to scope for. 1. Make a POST request to the `/webhook_subscriptions` [endpoint](/api-docs/b3A6NTkxNDI1-create-webhook-subscription). 2. Add your personal access token to authenticate the request. 3. Set your server endpoint in the `url` value. 4. Set `invitee.created,` or `invitee.canceled,` or `routing_form_submission.created` (or all 3) for the `events` value 5. Choose the `user` or `organization` value to isolate scheduled events to yourself or the organization. 1. Example request: `curl --request POST --url https://api.calendly.com/webhook_subscriptions --header 'Content-Type: application/json' --header 'authorization: Bearer ' --data '{ "url":"http://yourserverendpoint.com", "events":["invitee.created", "invitee.canceled"], "organization":"https://api.calendly.com/organizations/AAAAAAAAAAAAAAAA", "scope":"organization"}' ` 6. (Optional) To get data about an invitee such as name, email, and their answers to custom questions on an event booking page, use the URI property in the webhook payload to make a GET request to the `/scheduled_events/{event_uuid}/invitees/{invitee_uuid}` [endpoint](/api-docs/b3A6NTkxNDE1-get-event-invitee). When an invitee cancels an event, you can match them to an existing invitee in your system by comparing the URI. This will allow you to exclude the invitee or event from your data, or specifically track canceled or rescheduled events. See more --- [See how webhook payloads change when invitees reschedule events](/see-how-webhook-payloads-change-when-invitees-reschedule-events) --- ---- url: https://developer.calendly.com/creating-an-oauth-app ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Creating an OAuth app Creating an OAuth app ===================== Follow the procedure below to register and authenticate your public application with the Calendly API v2. Register your OAuth application --- - Sign up for a Calendly developer account using your Github or Google account by clicking the Sign Up button found in the top right corner of this page. Note: This is not your Calendly user account and is not associated with your Calendly user account. - Create a new OAuth application - Provide name of your application - Select the kind of application (web or native) - Select your environment that you want to associate your application - Sandbox - Production - We recommend starting with Sandbox for development and creating a second application for Production when ready to go live with customer data. - Redirect URI:  - For the Sandbox environment, we allow HTTP with localhost domain. Example: [http://localhost:1234](http://localhost:1234/)  - For the Production environment, this must be HTTPS - Select scopes based on the Calendly data and functionality that your OAuth app requires access to. Learn more about [scopes](/scopes). - For all OAuth applications (web or native) use a specific redirect_uri, a Proof Key for Code Exchange (PKCE), and S256 for code_challenge_method. For more information about PKCE, see [this guide](https://oauth.net/2/pkce/). - Proceed into the next step to view/copy your Client Id, Client Secret and Webhook signing key. Be sure to copy these values as you will not be able to access the Client Secret or Webhook signing key again. Test your application --- While we will not enforce PKCE for web applications, we recommend using PKCE conforming to the RFC 7636 specification for both web and native applications. For more information, see [this guide](https://oauth.net/2/pkce/). An example of a javascript implementation can be found [here](https://github.com/aaronpk/pkce-vanilla-js). To receive an Authorization Code: - Generate a `CODE_VERIFIER` - Build a `CODE_CHALLENGE` - Redirect the user to Calendly's authorization page with the `client_id`, `redirect_uri`, and `code_challenge` replaced with your application's `client_id`, `redirect_uri`, and the `code_challenge` generated in the step above (see example below). Note that this url must be requested using a web browser. https://auth.calendly.com/oauth/authorize?client\_id=CLIENT\_ID &response_type=code &redirect_uri=com.site.app://auth/calendly &code_challenge_method=S256 &code_challenge=CODE_CHALLENGE After the user grants access, they will be redirected back to your app with the Authorization Code: com.site.app://auth/calendly? code=f04281d639d8248435378b0365de7bd1f53bf452eda187d5f1e07ae7f04546d6 To receive an access token: - [Send a POST request](/api-docs/be9b32ef4b44c-get-access-token#request-body) to [https://auth.calendly.com](https://auth.calendly.com) with the `grant_type`, `code`, and `redirect_uri`  Edit your application --- --- Learn what else you can [accomplish with the Calendly API](/api-use-cases). For more information about conditions that result in an access token being revoked, please see our [Frequently Asked Questions](/frequently-asked-questions). --- ---- url: https://developer.calendly.com/view-event-type-and-user-calendar-availability-data ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) View availability data How to get event type and user calendar availability data ========================================================= Event Type Availability Calendly users can retrieve information about availability for a specific event type when they generate and use a [personal access token or OAuth token](/when-to-choose-between-personal-access-tokens-and-oauth) to authenticate requests to Calendly’s API.  Use cases that can be achieved with this API: - Take appropriate action based on available times for a given event type. - Effectively share available meeting times from an external application to increase the probability of meetings being booked and enhance the invitee experience. - For example:  - Display specific available times when sending communications to invitees directly from external applications. - Include and share first 'X' available times. To retrieve a list of available times for a specific event type within a specified date range: 1. Make a call to [/event_types](/api-docs/25a4ece03c1bc-list-user-s-event-types) to retrieve a list of all event types (using the organization scope to get all event types across the organization or using the user scope to get all event types for a specific user). The endpoint will return a collection of event types with an event type  uri for each item in the array.  2. Make a call to [/event_type_available_times](/api-docs/6a1be82aef359-list-event-type-available-times) and pass the event type uri for the event type you would like to retrieve information about. Please note that start_time and end_time parameters are required, must be in the future, and cannot be a range greater than 7 days.  User Calendar Availability  Calendly users can retrieve information about the availability of users in their organization when they generate and use a [personal access token or OAuth token](/when-to-choose-between-personal-access-tokens-and-oauth) to authenticate requests to Calendly’s API.  Use cases that can be achieved with this API: - Programmatically calculate total hours available for a given user for a given period of time. For example: - Total available hours - Total scheduled hours - Build a custom ‘Calendar View’ for a given user.  - View availability schedules and date overrides to determine if a user needs to open up more availability options. To retrieve information about a specific user’s availability schedule and their busy times for a given period, make the following GET requests:  To retrieve the availability schedules and date overrides for a specific user: 1. Make a call to [/organization_memberships](/api-docs/eaed2e61a6bc3-list-organization-memberships) to return a collection of users in an organization which includes a user.uri for each item in the array. 2. Make a call to [/user_availability_schedules](/api-docs/8098de44af94c-list-user-availability-schedules) and pass the specified user.uri . To retrieve busy times for a specific user (based upon the connected calendars marked as “Check for Conflicts” in Calendly): 1. Make a call to [/organization_memberships](/api-docs/eaed2e61a6bc3-list-organization-memberships) to return a collection of users in an organization which includes a user.uri for each item in the array. 2. Make a call to [/user_busy_times](/api-docs/5920076156501-list-user-busy-times) and pass the specified user.uri . Please note that start_time and end_time parameters are required, must be in the future, and cannot be a range greater than 7 days. --- ---- url: https://developer.calendly.com/getting-started ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Getting started Getting started with the Calendly API ===================================== Put your data to work so you can accomplish tasks quicker --- We currently provide three APIs for you to integrate Calendly into your application:  API v2: Our current, actively maintained API. The Calendly API v2 is [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer)\-based and has predictable resource-oriented URLs. It uses JSON for request and response bodies and standard HTTP methods, authentication, and response codes. Embed API: Our simpler, easy-to-use API that lets you add a Calendly landing or booking page to your website. See [how to add Calendly to your website](https://help.calendly.com/hc/en-us/articles/223147027-Embed-options-overview?tab=general#3). Webhook API: Our friendly, lightweight API that lets you automatically receive Calendly data with webhook subscriptions anytime invitees schedule, cancel, or reschedule a meeting.Build integrated apps for your team or customers Authenticating requests --- The Calendly API v2 uses personal access tokens and OAuth 2.1 to authenticate requests. Choose either depending on who's using the application you're integrating with Calendly. - If you're integrating an internal application that only your team will use, authenticate with personal access tokens. - If you're integrating a public application that many Calendly users will use, authenticate with OAuth. To see specific examples of when you might choose either authentication method, refer to the [authentication overview](/authentication). ### Review your API and webhook permissions Access to the Calendly API is determined by your [subscription](https://calendly.com/pricing) and user role in Calendly, while access to webhooks is reserved for members on paid premium subscriptions and above. If your user role is not sufficient, some HTTP methods, including those that access organization-wide Calendly data, may not be available to you or others because of insufficient user privileges. To find out who in your Calendly organization has owner or admin permissions, visit your [People/Admin Management page](https://calendly.com/app/organization/users). ### What's next [Personal access tokens overview](/personal-access-tokens) [Creating an OAuth app](/creating-an-oauth-app) --- ---- url: https://developer.calendly.com/api-use-cases ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) API Use Cases Accomplish tasks with the Calendly API ====================================== See the articles below to help you get started with the Calendly API for specific use cases you may have. To access and use Calendly data, you'll need to [authenticate with the Calendly API](/getting-started) to retrieve your personal access token or OAuth token. Sharing the scheduling pages of team members in your organization --- Enhance your productivity when you use these guides to access the scheduling links of team members in your Calendly organization or add Calendly to your website for easy scheduling. [How to get scheduling page links for team members across the organization (admins only)](/how-to-get-scheduling-page-links-for-team-members-across-the-organization) [How to add Calendly to your website for simple scheduling](/how-to-display-the-scheduling-page-for-users-of-your-app) Working with webhooks to analyze data or trigger automations --- Put your data to work when you use these guides to receive, understand, and report on Calendly data when it arrives at an endpoint you specify. [How to receive data from scheduled events in real time with webhook subscriptions](/receive-data-from-scheduled-events-in-real-time-with-webhook-subscriptions) [How to understand webhook payloads when invitees reschedule events](/see-how-webhook-payloads-change-when-invitees-reschedule-events) [How to track and report on all scheduled events across your organization](/track-and-report-on-all-scheduled-events-across-your-organization) Bridging the gap between Calendly and your app --- Provide a seamless experience when you help users of your app create new Calendly accounts without ever leaving it. When you want to enhance their experience further, access and use Calendly data on their behalf so they can focus on scheduling. [How to enable users to create new Calendly accounts without leaving your app](/enable-users-to-create-new-calendly-accounts-without-leaving-your-app) [How to access Calendly data on behalf of authenticated users](/how-to-access-calendly-data-on-behalf-of-authenticated-users) --- ---- url: https://developer.calendly.com/see-how-webhook-payloads-change-when-invitees-reschedule-events ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Webhook Payloads for rescheduled events See how webhook payloads change when invitees reschedule events =============================================================== When an invitee reschedules an event, both webhook events (`invitee.created` and `invitee.canceled`) will be triggered. Understanding the payloads --- When you receive the payloads at your URL, take note of a few key differences between the payloads: - the `invitee.canceled` webhook payload will contain the data for the event that was canceled and include the value of true on the `rescheduled` key`.` When False shows on the `rescheduled` key, this indicates the event has not been rescheduled and is solely a canceled event by an invitee. - The `invitee.created` payload will contain the event data for the new event created from the reschedule. You'll notice the `status` of the event is now `active` since the invitee is attending this newly created event (the rescheduled event from the canceled event.) - Please note that you can reference the value for the new invitee URI and the old invitee URI in this payload - The old (`old_invitee`) and new (`new_invitee`) URI references are located on the invitee model, and not the event model since the reschedule is per invitee and not the per event.  When making a call for the invitee resource [/scheduled_events/{event_uuid}/invitees/{invitee_uuid}](/api-docs/b3A6NTkxNDE1-get-event-invitee), there is a key of `status` which will indicate if this is an active invitee. --- ---- url: https://developer.calendly.com/personal-access-tokens ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Personal access tokens Personal access tokens overview =============================== Follow the procedures below to generate a personal access token and authenticate an internal or private application with the Calendly API v2. Do not share your personal access token with public sources or reuse it across applications. To further secure your personal access tokens, we do not display or store them in your Calendly account. After generation, they’re unretrievable. - [Log in](https://calendly.com/login) to your Calendly account - Go to the [Integrations Page](https://calendly.com/integrations) - Select the [API & Webhooks tile](https://calendly.com/integrations/api_webhooks) - If you have no prior personal access tokens, select Get a token now under Personal Access Tokens. - If you already have a token, select Generate new token under Your personal access tokens. - At Create your personal access token, create an identifiable name for your token and select Create Token, then Copy token. Note: If you need to register and authenticate a public application, see: [Creating an OAuth app](/creating-an-oauth-app) Scopes --- Based on the Calendly data and functionality that your app will require access to, you’ll provide a list of scopes when creating a personal access token. Learn more about [scopes](/scopes). What's next --- Learn what else you can [accomplish with the Calendly API](/api-use-cases). For more information about conditions that result in an access token being revoked, please see our [Frequently Asked Questions](/frequently-asked-questions). --- ---- url: https://developer.calendly.com/how-to-authenticate-with-personal-access-tokens ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) How to authenticate Calendly API with personal access tokens How to authenticate with personal access tokens =============================================== Follow the procedures below to generate a personal access token and authenticate an internal or private application with the Calendly API v2. Do not share your personal access token with public sources or reuse it across applications. To further secure your personal access tokens, we do not display or store them in your Calendly account. After generation, they’re unretrievable. Note: If you need to register and authenticate a public application, see: [Create a Calendly developer account](/create-a-developer-account) - [Log in](https://calendly.com/login) to your Calendly account - Go to the [Integrations Page](https://calendly.com/integrations) - Select the [API & Webhooks tile](https://calendly.com/integrations/api_webhooks) - If you have no prior personal access tokens, select Get a token now under Personal Access Tokens. - If you already have a token, select Generate new token under Your personal access tokens. - At Create your personal access token, create an identifiable name for your token and select Create Token, then Copy token. What's next --- Learn what else you can [accomplish with the Calendly API](/api-use-cases). For more information about conditions that result in an access token being revoked, please see our [Frequently Asked Questions](/frequently-asked-questions). --- ---- url: https://developer.calendly.com/refresh-token-rotation-guide ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Refresh token rotation guide How to handle single‑use refresh tokens ======================================= Calendly is updating its OAuth 2.1 implementation to better protect against token replay and abuse. The main change is in how refresh tokens behave when you call the `POST /oauth/token endpoint`. This guide explains what’s changing and shows the correct way to implement refresh token rotation so your integration keeps working smoothly. --- What’s Changing --- Previously, a refresh token could be successfully reused multiple times, and was only revoked indirectly after an access token created from it was used. Going forward, Calendly will use single‑use refresh tokens with rotation, aligned with OAuth 2.1 best practices: - A refresh token is revoked immediately after a successful `POST /oauth/token` call. - Each successful response from `POST /oauth/token` will still return: - a new access token, and - a new refresh token. - Access token behavior (lifetime, scopes, etc.) does not change. If your integration tries to reuse a refresh token that has already been used, the request will fail after this change. --- How Your Integration Should Handle Refresh Tokens --- Calendly recommends that your OAuth client: - Treats refresh tokens as single‑use. - Immediately overwrites the stored refresh token with the new `refresh_token` from every successful `POST /oauth/token` response. - Does not keep or reuse older refresh token values. In practice, your logic should be: 1. Call `POST /oauth/token` with the current authorization code or refresh token. 2. On success, update your storage with the new `access_token` and `refresh_token` from the response. 3. Only ever use the most recently stored refresh token for future refreshes. If you already overwrite the stored refresh token on each successful refresh today, you should not need to change your integration. --- Example: Correct Refresh Token Rotation --- Here’s a simplified pattern you can adapt to your code. ### Handling a Token Response async function handleTokenResponse(userId, tokenResponse) { await db.updateUserTokens({ userId, accessToken: tokenResponse.access\_token, // Always remove the old refresh token refreshToken: tokenResponse.refresh\_token, accessTokenExpiresAt: new Date(Date.now() + tokenResponse.expires\_in \* 1000), }); } ### Refreshing an Access Token Safely async function refreshAccessToken(userId) { const tokens = await db.getUserTokens(userId); if (!tokens || !tokens.refreshToken) { return null; } const response = await fetch('/oauth/token', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', }, body: new URLSearchParams({ grant\_type: 'refresh\_token', refresh\_token: tokens.refreshToken, client\_id: CLIENT\_ID, }), }); if (response.status === 200) { const json = await response.json(); await handleTokenResponse(userId, json); // now includes NEW refresh token return db.getUserTokens(userId); } if (response.status === 400 || response.status === 401) { // Refresh token is invalid, expired, or already used. await db.clearUserTokens(userId); // If the refresh token is already invalid, reauthorize // the user to Calendly await promptUserToReconnectCalendly(userId); return null; } } This approach ensures: - Each refresh token is used once and rotated away. - On refresh failure (e.g., 400/401), you clear tokens and ask the user to re‑authorize instead of retrying endlessly. - Refresh tokens are handled only on the server side, in secure storage. --- Next Steps, Timeline, and Support --- The deadline for updating your refresh token behavior is August 31, 2026. Before then, we recommend: - Reviewing your token storage and rotation logic. - Confirming you overwrite refresh tokens on each successful refresh. - Verifying that your error handling cleanly falls back to a new authorization when a refresh fails. If you have questions or need help updating your integration, please contact [Calendly developer support](/get-help). FAQs --- Q: What changed with Calendly’s OAuth refresh tokens? A: Calendly is updating its OAuth implementation to use single-use refresh tokens with rotation, per OAuth 2.1 guidelines. Previously, a refresh token could be reused multiple times to get new access tokens. Going forward, each refresh token can only be used once, when you use it to refresh, that refresh token becomes invalid and you’ll get a new refresh token in the response . This means your integration needs to update the stored refresh token every time you refresh the access token. The access tokens themselves and their lifespans haven’t changed, but refresh tokens now rotate on each use for improved security. Q: Why is Calendly making this change? A: This change is to improve security and align with OAuth 2.1 best practices. Single-use (rotating) refresh tokens help protect against token replay attacks and abuse. OAuth 2.1 formalizes an approach to make integrations more secure . In short, it’s a proactive upgrade to keep your data safe and adhere to the latest standards. Q: What do I need to update in my integration? A: You need to ensure your OAuth client code handles refresh tokens as single-use and implements refresh token rotation. In practice, this means: after calling `POST /oauth/token` (to either get initial tokens or refresh them), take the new refresh_token returned in the response and save it (replace the old one) . Do not reuse the old refresh token again. Always use the latest refresh token that was issued. Most OAuth libraries that handle refresh tokens already have support for this, double-check your library’s docs. If you implemented the flow manually, you may need to add logic to update the stored token. Also, make sure your error handling is ready: if you do accidentally use an outdated refresh token, the API will return an invalid_grant error, and your integration should catch that and prompt the user to re-connect their Calendly account (obtaining a new authorization code) . Q: Will my existing refresh tokens stop working? Do users need to re-authenticate right now? A: There’s no immediate hard cut-off that invalidates all refresh tokens, but behavior is changing once the feature rolls out. Existing refresh tokens will still work, but only for one use each once rotation is enforced. This means as soon as you use a refresh token under the new system, that particular token won’t work again. Your integration should seamlessly handle this by using the new refresh token that comes back. End-users do not have to re-authenticate immediately if your integration is updated to handle rotation. They might have to re-auth later if a refresh token gets invalidated and your code wasn’t updated (in which case your app would likely ask them to log in again). To avoid forcing re-auth, implement the rotation logic now so the transition is smooth. Calendly will notify developers of the timeline; we suggest updating your code before the hard enforcement date to ensure continuity. Q: How will I know if I’ve implemented refresh token rotation correctly? A: A good test is to go through a token refresh cycle twice in a row and see if the second attempt succeeds. For example, simulate your token refresh process: use refresh token R1 to get a new token (response gives you new refresh token R2). Then try to use R1 again (which should fail if rotation is working), and use R2 to get another token (which should succeed and yield R3). In a properly implemented integration, you would never actually try R1 again because you’d have replaced it with R2 internally. But this thought experiment illustrates what should happen: any attempt to reuse a refresh token that’s already been used will be rejected by Calendly . If your integration always uses the latest refresh token and that flow works continuously, you’ve done it right. Q: What error will I get if I don’t update my code? A: If your code reuses an old refresh token, the Calendly API will respond to the refresh request with an error. Specifically, you’ll get HTTP 400 (Bad Request) or 401, and the JSON error will be "invalid_grant" (with a description like “authorization grant is invalid, expired, or revoked”). This is the same error used for an expired or truly invalid token, but in this case it means the token was already used and is now revoked. If you see this error when refreshing, it’s a strong indicator that your code attempted to use a refresh token more than once. The solution is to obtain a new authorization (if you’ve lost the latest token) and implement the rotation logic going forward. Q: Is there a deadline for making these changes? A: Calendly is rolling out the refresh token rotation in early 2026 and will enforce it for all integrations by mid-2026. We haven’t publicly announced an exact cut-off date in this FAQ answer, but expect that by summer 2026 all apps must adhere to the new behavior. Calendly will send out communications (emails, developer portal announcements) with the specific timeline. It’s highly recommended to update your integration now rather than waiting. If you don’t update, your integration will start failing to refresh tokens once the enforcement is in place. In short: there is a firm deadline (approximately six months from announcement) after which non-rotating integrations will no longer function correctly . Q: My app was working fine, why fix it if it isn’t broken? A: While your integration might appear fine today, the change is about to be in effect or already active for new apps. If your app is older, Calendly provided a grace period, but that will end. Think of this like depreciation of an old API method, it might still work for now, but it’s officially deprecated and will be removed. If you don’t “fix it,” it will break in the near future. Moreover, even during the grace period, adopting the new logic is beneficial for security. It’s not just about compliance; it ensures your integration is following the recommended security practices, which protects you and your users. Making the update now prevents future emergencies when the old behavior is turned off. --- ---- url: https://developer.calendly.com/api-recipes ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) API Recipes Accelerate Your Integration: Power Up with our API Recipes! =========================================================== Explore our collection of API recipes, thoughtfully curated to assist you in tackling common challenges and streamlining your development process. These recipes serve as practical, code-based solutions to real-world problems, providing quick integration, best practices, and valuable learning resources. Whether you're a seasoned developer or just getting started, our API recipes will save you time, ensure code reusability, and foster community engagement. Unlock the potential of our API and take your projects to new heights with these versatile and customizable recipes at your disposal. --- ---- url: https://developer.calendly.com/how-to-access-calendly-data-on-behalf-of-authenticated-users ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) How to access Calendly data on behalf of authenticated users How to access Calendly data on behalf of authenticated users ============================================================ Use Calendly’s API v2 to authenticate your app’s users with OAuth and access Calendly data on their behalf. To get started, follow the steps below. 1. [Create a Calendly developer account](/create-a-developer-account) to get started. 2. To initiate the OAuth authorization flow, use your application's `client_id` and redirect your user to [Get Authorization Code](/api-docs/b3A6NTkxNDA5-get-authorization-code) endpoint. Once the Calendly user grants access, their browser is redirected to your application's specified `redirect_uri` and the Authorization Code is passed inside the `code` query parameter. Notes: - This URL must be requested using a web browser. - The authorization code expires after 10 minutes. Example Request URL: `https://auth.calendly.com/oauth/authorize?client_id=CLIENT_ID&response_type=code&redirect_uri=https://my.site.com/auth/calendly` Example Redirect URL: `https://my.site.com/auth/calendly?code=f04281d639d8248435378b0365de7bd1f53bf452eda187d5f1e07ae7f04546d6 ` 3. To retrieve the access token, make a POST request to [Get Access Token](/api-docs/b3A6NTkxNDA4-get-access-token) endpoint. Use it to access Calendly resources on behalf of an authenticated user. Note: - Access tokens expire after 2 hours. - Use a refresh token to get a new access token. - Refresh tokens don't expire until they are used. 4. To test the access token, make a call to the [Get current user](/api-docs/b3A6MTEzMDIyOQ-get-current-user) endpoint. --- ---- url: https://developer.calendly.com/api-docs ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Now Available: Scheduling API --- Build scheduling directly into your app without redirects, iframes, or Calendly-hosted UI. Ideal for AI assistants, automation tools, and custom portals. [Documentation available here.](https://developer.calendly.com/api-docs/p3ghrxrwbl8kqe-create-event-invitee) Open the API Reference on desktop for the best experience. Otherwise please refer to our[Stoplight Documentation](https://calendly.stoplight.io/docs/api-docs) ---- url: https://developer.calendly.com/calendly-mcp-server ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Calendly MCP Server Calendly MCP Overview ===================== The Calendly MCP server enables AI-powered apps and developers to securely connect to Calendly using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro). It translates natural-language commands (e.g., “Book a 30-minute meeting with Sam next Tuesday”) into structured Calendly API calls with no need to implement raw REST requests. The server is fully hosted by Calendly at `https://mcp.calendly.com`. Self-hosting or local deployment is not supported. Before you build — check client compatibility. Calendly MCP uses DCR (RFC 7591), so clients self-register to obtain a `client_id` at runtime. If your MCP client prompts you to paste in a `client_id` and `client_secret` from a developer console, it does not support DCR and will not work with Calendly MCP today. Supported Today Not Supported Today OAuth flow ✅ OAuth 2.1 Authorization Code + PKCE (S256) ❌ Manual OAuth app provisioning (console-issued credentials) Registration ✅ Dynamic Client Registration (DCR, RFC 7591) ❌ Static, pre-registered `client_id` flows without DCR Auth method ✅ OAuth discovery via protected resource metadata ❌ Non-OAuth bearer tokens (e.g. personal access tokens) Key benefits - Secure, standards-based OAuth 2.1 authentication - Full coverage of Calendly's scheduling capabilities - Compatible with any MCP-compliant client or agent framework - Same scopes and permissions as Calendly's public API Authentication model ==================== Calendly MCP uses Dynamic Client Registration (DCR), which means you do not need to pre-register an OAuth application or put any OAuth secrets into your MCP client configuration. After setting the server URL, the client and server navigate the auth flow automatically. Once Calendly MCP is connected to a client, it generates an OAuth application for the session. A browser window opens for the user to grant access to their Calendly account. After pressing "Connect to Calendly" on the consent screen, the scheduling tools are available immediately. For developers building custom MCP clients, the full DCR walkthrough is in Section 3. At a high level: 1. The MCP endpoint is an OAuth-protected resource. 2. An unauthenticated request returns 401 with a link to the OAuth resource metadata. 3. The client fetches that metadata to discover the authorization server and required scopes. 4. The client fetches authorization server metadata to find the token, auth, and `registration_endpoint`. 5. The client calls `registration_endpoint` (DCR) to self-register and receive a `client_id`. 6. The client runs the Authorization Code + PKCE flow to obtain an access token. 7. The client sends the access token on all subsequent MCP calls. Integration walkthrough ======================= This section is for developers building their own MCP clients. If you're new to building MCP clients, see [Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client) and [Connect to remote MCP servers](https://modelcontextprotocol.io/docs/develop/connect-remote-servers) in the MCP docs. The steps below focus on: 1. Initial handshake between your MCP client and the Calendly MCP server. 2. Discovery of the Calendly MCP protected resource. 3. Discovery of the Calendly authorization server. 4. Registration of your MCP client via DCR. Step 0: Initial handshake --- When your MCP client first tries to call the Calendly MCP server without a token, the server responds with 401 Unauthorized and tells the client where to find the protected resource metadata document, as defined in RFC 9728. HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://mcp.calendly.com/.well-known/oauth-protected-resource" This tells the client that authorization is required for the Calendly MCP server and where to get the metadata needed to kick off the discovery and DCR flow. Step 1: Discover the Calendly MCP protected resource --- Your MCP client (or the MCP framework you’re using) should first discover the MCP server’s protected resource metadata. Request GET https://mcp.calendly.com/.well-known/oauth-protected-resource Accept: application/json Successful response (example) { "resource": "https://mcp.calendly.com/", "authorization_servers": \["https://calendly.com/"\], "scopes_supported": \[ "mcp:scheduling:read", "mcp:scheduling:write" \], "bearer_methods_supported": \["header"\] } Key points: - `resource` is the identifier your client should use when requesting tokens for the MCP server. - `authorization_servers` tells you which OAuth authorization server(s) to talk to (for Calendly MCP, this is `https://calendly.com/`). - scopes_supported lists the only scopes currently issued for MCP. Calendly MCP requires both for full access. - `mcp:scheduling:read` - `mcp:scheduling:write` Your DCR and later OAuth requests should treat this document as the source of truth for the MCP resource and scopes. Step 2: Discover the Calendly authorization server --- Next, discover the Calendly OAuth authorization server metadata. This tells you where to send DCR, authorization, and token requests. Request GET https://calendly.com/.well-known/oauth-authorization-server Accept: application/json Successful response (example) { "issuer": "https://calendly.com/", "authorization_endpoint": "https://calendly.com/oauth/authorize", "token_endpoint": "https://calendly.com/oauth/token", "registration_endpoint": "https://calendly.com/oauth/register" } Key field for DCR: - `registration_endpoint` – this is the URL you will call to dynamically register your MCP client. Step 3: Register your MCP client via DCR --- With the `registration_endpoint` discovered, your MCP client can register itself dynamically. - Endpoint: `POST https://calendly.com/oauth/register` - Authentication: For MCP, a registration token is not required, however the endpoint is heavily validated and rate‑limited. - Content type: `application/json` #### 3.1 Minimal valid registration request This is the minimal JSON body your MCP client should send to register: POST https://calendly.com/oauth/register Content-Type: application/json { "client_name": "My MCP Client", "redirect_uris": \[ "https://myapp.example.com/mcp/callback" \], "grant_types": \["authorization_code"\], "response_types": \["code"\], "token_endpoint_auth_method": "none" } Field notes - `client_name` - Human‑readable label shown on Calendly’s consent screen. - Should clearly identify your MCP client or product. - `redirect_uris` - Array of one or more redirect URIs. - For production: - Must be HTTPS. - Must be exact URIs (no wildcards like `https://*.example.com/...`). - Must not contain multiple schemes in a single URI (e.g., `https://http://...`). - Must not contain userinfo (e.g., `https://user@evil.example/...`). - Leading/trailing spaces are rejected. - For local development, `http://localhost/...` or `http://127.0.0.1/...` may be allowed per environment policy. - `grant_types` - For MCP, use: - \[`"authorization_code"`\] - Include `"refresh_token"` if your client will use refresh tokens. - `response_types` - MCP only supports the authorization code with PCKE flow: - \[`"code"`\] is required. - `token_endpoint_auth_method` - For MCP DCR, Calendly treats clients as public and requires: - `"none"` - That implies: - No `client_secret` is used at the token endpoint. - PKCE is required to protect the authorization code. - Scopes - Calendly MCP currently issues: - `mcp:scheduling:read` - `mcp:scheduling:write` - These are configured server‑side for MCP DCR clients. - You do not need to include `scope/scopes` in the registration request. The server will attach the MCP scopes for you. #### 3.2 Successful registration response On success, you’ll receive a JSON document describing your new client: { "client_id": "auto-generated-client-id", "client_name": "My MCP Client", "redirect_uris": \[ "https://myapp.example.com/mcp/callback" \], "scopes": \[ "mcp:scheduling:read", "mcp:scheduling:write" \], "grant_types": \[ "authorization_code" \], "response_types": \[ "code" \], "token_endpoint_auth_method": "none" } Important points: - `client_id` - Opaque identifier your MCP client must use in all later OAuth interactions. - Treat it as a stable, long‑lived identifier. - `client_secret` - For MCP DCR, no client secret is issued (public client). - Your MCP client must rely on PKCE and `token_endpoint_auth_method: "none"`. - scopes - Confirms the scopes assigned to this client. - For MCP, expect `["mcp:scheduling:read", "mcp:scheduling:write"]`. Store at least: - `client_id` - `redirect_uris` - Any metadata your MCP framework expects for subsequent authorization and token requests. #### 3.3 Error responses and validation behavior If the registration request is invalid, the endpoint returns an error: { "error": "invalid_client_metadata", "errors": { "redirect\_uri": \[ "must start with https in Production." \] } } Other examples you might encounter: - Invalid scopes: { "error": "invalid_client_metadata", "errors": { "scopes": { "0": \[ "must be one of: mcp:scheduling:read, mcp:scheduling:write" \] } } } - Wildcard or malformed redirect URIs, multiple schemes, or leading spaces: { "error": "invalid_client_metadata", "errors": { "redirect\_uri": \[ "must be an exact https URI without wildcards or user info." \] } } When you receive `invalid_client_metadata`: 1. Inspect the `errors` object to see which field(s) failed validation. 2. Correct the JSON body (e.g., fix `redirect_uris`, adjust scopes, remove wildcards). 3. Retry the `POST /oauth/register` request. --- With these steps, your custom MCP client can perform standards‑based Dynamic Client Registration against Calendly’s authorization server, using only: - Discovery URLs: - `https://mcp.calendly.com/.well-known/oauth-protected-resource` - `https://calendly.com/.well-known/oauth-authorization-server` - DCR endpoint: - `https://calendly.com/oauth/register` Once registered, you can proceed with the standard OAuth 2.1 authorization code + PKCE flow using the discovered `authorization_endpoint` and `token_endpoint`, and the `client_id` returned from DCR. Supported tools =============== The Calendly MCP server exposes tools mapped to Calendly's public API v2. Each [tool includes annotation metadata](https://modelcontextprotocol.io/legacy/concepts/tools#available-tool-annotations) — a human-readable title and hints (readOnlyHint, destructiveHint, idempotentHint) — to enhance the user experience and optimize repeated calls. See the [full list of Calendly MCP server tools](/supported-tools). Example prompts =============== Prompt Result “List my event types.” Returns the user’s event types “Find open slots next week for my 30 min coaching session.” Lists available time ranges “Remove Fridays as available days for scheduling 30 min coaching sessions.” Updates availability “What is my scheduling link for 30 min coaching sessions?” Returns a scheduling link “Book a 30 min coaching session with User A ([user@email.com](mailto:user@email.com)) for this Thursday at 2 PM.” Creates a scheduled event “Cancel my 2 PM coaching session.” Cancels a scheduled event “Generate a one-time scheduling link for my 30 min coaching session.” Creates a single-use link --- ---- url: https://developer.calendly.com/how-to-find-the-organization-or-user-uri ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) How to find the organization or user URI How to find the organization or user URI ======================================== Make a GET request to /users/me --- To get the user URI, call `GET` [`/user/me`](/api-docs/b3A6MTEzMDIyOQ-get-current-user) to get the organization and user URI. Replace the `{access_token}` value with your [OAuth](/how-to-authenticate-with-oauth) or [personal access token](/how-to-authenticate-with-personal-access-tokens). Example request:` curl --request GET \ --url https://api.calendly.com/users/me \ --header 'authorization: Bearer {access_token}'` Review the response payload (for personal access tokens) --- If you authenticated with your personal access token, the payload will contain information about you and your Calendly account. Note the values of the resources in the payload: - the user URI is given as the value of `uri` - the organization URI is given as the value of `current_organization` Review the response payload (for OAuth) --- If you authenticated with OAuth, the organization and user URI are referenced differently in the [access token’s payload](/api-docs/b3A6NTkxNDA4-get-access-token): - the user URI is given as the value of the `owner` key - the organization URI is given as the value of the `organization` key Find the organization or user URI for all Calendly members in your organization --- If you already have a specific user or organization URI, use it to make a GET request to `/organization_memberships` [endpoint](/api-docs/b3A6NTkxNDI0-list-organization-memberships) which will return information about a user’s membership to an organization, or a collection of all Calendly members in the organization, respectively. Review the response payload (for personal access tokens) --- Depending on which URI you’ve used, the payload will contain information about your membership status to an organization, or information about all Calendly members in the organization. Note the values of the resources in the payload: - the user URI is given as the value of `uri` - the organization URI is given as the value of `organization` In the user object of each collection, Calendly returns the user's `organization` URI and user URI as `uri`. What's next --- [How to get scheduling page links for any team member across the organization (admins only)](/how-to-get-scheduling-page-links-for-team-members-across-the-organization) [Track and report on all scheduled events across the organization (admins only)](/track-and-report-on-all-scheduled-events-across-your-organization) --- ---- url: https://developer.calendly.com/scopes ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Scopes Authorization Scopes ==================== Overview --- Authorization scopes define the permissions that an application requests when accessing Calendly APIs on behalf of a user. Scopes control which Calendly resources your integration can read or modify. When a user installs your app, the scopes you request determine what actions your app is permitted to perform. Scopes follow these rules: Read vs Write - Read scopes allow safe retrieval of data. - Write scopes allow creation, modification, or deletion of data. Hierarchy - A `:write` scope implicitly includes the corresponding `:read` scope within the same domain. Webhooks - Webhook subscriptions must be scoped by the event family you want to receive. Your app must be granted the related read scopes to receive webhook event payloads. Scope Catalog --- Category Scope Description Provides access to Scheduling `availability:read` Retrieve user and event-type availability. `GET /user_busy_times` `GET /user_availability_schedules` `GET /user_availability_schedules/{uuid}` `GET /event_type_availability_schedules` `availability:write` Update event type availability. `PATCH /event_type_availability_schedules/{uuid}` `event_types:read` Retrieve event type details and available times. `GET /event_types, GET /event_types/{uuid}`  `GET /event_type_available_times` `GET /event_type_memberships` `event_types:write` Create or update event types. `POST /event_types` `PATCH /event_types/{uuid}` `POST /one_off_event_types` `locations:read` Retrieve configured meeting locations. `GET /locations` `routing_forms:read` Retrieve routing forms and submissions. `GET /routing_forms` `GET /routing_forms/{uuid}` `GET /routing_form_submissions` `GET /routing_form_submissions/{uuid}` `shares:write` Create and customize a single-use scheduling link from an existing event type. `POST /shares` `scheduled_events:read` Retrieve scheduled events and event invitee information. `GET /scheduled_events` `GET /scheduled_events/{uuid}` `GET /scheduled_events/{uuid}/invitees` `GET /scheduled_events/{uuid}/invitees/{invitee_uuid}` `GET /invitee_no_shows/{uuid}` `scheduled_events:write` Create event invitees, cancel events or mark invitees as no-show. `POST /invitees` `POST /scheduled_events/{uuid}/cancellation` `POST /invitees/{uuid}/no_show` `DELETE /invitees/{uuid}/no_show` `scheduling_links:write` Create a single-use scheduling link from an existing event type without any customization. `POST /scheduling_links` User management `groups:read` Retrieve group details and relationships. `GET /groups` `GET /groups/{uuid}` `GET /group_relationships` `GET /group_relationships/{uuid}` `organizations:read` Retrieve organization data, memberships, and invitations. `GET /organizations/{uuid}` `GET /organization_memberships` `GET /organization_memberships/{uuid}` `GET /organization_invitations` `GET /organization_invitations/{uuid}` `organizations:write` Invite or remove users from an organization. `POST /organization_invitations` `DELETE /organization_invitations/{uuid}` `DELETE /organization_memberships/{uuid}` `users:read` Retrieve user information. `GET /users/{uuid}` `GET /users/me` Webhooks `webhooks:read` Retrieve webhook subscriptions and sample payloads. `GET /webhook_subscriptions` `GET /webhook_subscriptions/{uuid}` `GET /webhook_subscriptions/sample_data` `webhooks:write` Create or delete webhook subscriptions.  `POST /webhook_subscriptions` `DELETE /webhook_subscriptions/{uuid}` Security & Compliance `activity_log:read` View organization activity. `GET /activity_log_entries` `data_compliance:write` Delete invitee or event data. `POST /data_compliance/deletion_event` `POST /data_compliance/invitee_deletion` `outgoing_communications:read` Retrieve a list of outgoing SMS and email communications. `GET /outgoing_communications` Required Scopes Per Endpoint --- Each API endpoint in the reference includes a “Required scopes” section that tells you which Auth scopes must be granted for the request to succeed. Example callout: When a request is missing required scopes, the API returns an error indicating insufficient permissions. Choosing Scopes --- When your app initiates an OAuth flow, it should request the minimum set of scopes needed for your use cases. Overly broad scopes can lead to unnecessary user friction at install time. Review your integration’s features and map them to the scopes in the catalog above. Example: Syncing basic scheduling data into a third party system - `scheduled_events:read` Required to read scheduled meetings and their status. - `invitees:read` Required to associate meetings with people and contact details. - `webhooks:write` (optional) Recommended for near real time updates. Not required if the integration relies on polling. Troubleshooting --- Missing scope error If you receive a 403 error indicating missing scopes: 1. Verify that the scopes requested during installation include all required by the endpoint you are calling. 2. Confirm that the user granted all requested scopes (users can decline scopes during install). 3. For existing installs, you may need to reauthorize the app to request additional scopes. Webhooks not delivering events - Check that `webhooks:write` is granted. - Confirm that your subscription includes the event family you want to receive. - Ensure that the related domain read scopes are also granted. Backward Compatibility --- Legacy OAuth apps and Personal Access Tokens issued before the introduction of scoped permissions retain full access to available endpoints by default. For newly created OAuth apps and new Personal Access Tokens, no API access is granted until scopes are explicitly requested and approved. When a legacy token is refreshed, it is automatically migrated to the scoped token format. This migration happens transparently and does not require the user to reauthorize the application. Sample Authorization URL --- Replace `CLIENT_ID` and `REDIRECT_URI` with your values: https://auth.calendly.com/oauth/authorize ?client_id=CLIENT_ID &redirect_uri=REDIRECT_URI &response_type=code &scope=scheduled_events:read webhooks:write List scopes separated by spaces. Only include the scopes your app needs. --- ---- url: https://developer.calendly.com/release-notes ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Release notes Now Available: Scheduling API --- Build scheduling directly into your app without redirects, iframes, or Calendly-hosted UI. Ideal for AI assistants, automation tools, and custom portals. [Documentation available here.](https://developer.calendly.com/api-docs/p3ghrxrwbl8kqe-create-event-invitee) See what’s new with Calendly’s API ================================== RSS: [https://developer.calendly.com/rss.xml](/rss.xml) Atom: [https://developer.calendly.com/atom.xml](/atom.xml) Show 3 months 1 - NaN of 32 --- ---- url: https://developer.calendly.com/update-your-system-with-data-from-scheduled-events-admins-only ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Update your system with data from scheduled events (admins only) Update your system with data about scheduled events (admins only) --- 1. As an owner or admin in your organization, [generate a personal access token](/how-to-authenticate-with-personal-access-tokens). 2. Before continuing, ensure that you have your organization’s URI. 3. To get information about all scheduled events in your organization, including canceled events, make a GET request to the `/scheduled_events` [endpoint](/api-docs/b3A6NTkxNDEy-list-events). You will need to provide the organization URI you found in step 2 in the organization parameter, and specify the `active` status to filter out canceled events. Optionally, add date parameters to isolate scheduled events within a range for more recent reporting. Example request: `curl --request GET \ --url 'https://api.calendly.com/scheduled_events?organization=https://api.calendly.com/organizations/AAAAAAAAAAAAAAAA&status=active' \ --header 'authorization: Bearer '` 4. (optional) To get data about all invitees associated with an event such as name, email, and their answers to custom questions on an event booking page, make a GET request to the `/scheduled_events/{event_uuid}/invitees/{invitee_uuid}` [endpoint](/api-docs/b3A6NTkxNDE1-get-event-invitee). Example request: `curl --request GET \  --url https://api.calendly.com/scheduled_events/CCCCCCCCCCCCCCCC/invitees \  --header 'authorization: Bearer '` 5. When you periodically pull more information from `/scheduled_events`, set the `min_start_time` to the date and time of your last request because event information will not be changed once an event is in the past. 6. To determine whether the event is already included in your report, compare scheduled event URIs. Exclude the `status` parameter so you can exclude/handle any canceled events (by checking the status property of a scheduled event). See more --- [Trigger automations with other apps when invitees schedule, cancel, or reschedule events](/trigger-automations-with-other-apps-when-invitees-schedule-or-cancel-events) --- ---- url: https://developer.calendly.com/how-to-authenticate-with-oauth ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) 404 Unfortunately we can't find the page you're looking for ======================================================= The link you have clicked may be broken or the page has been removed [Return Home](/)[support+developer@calendly.com](mailto:support+developer@calendly.com) --- ---- url: https://developer.calendly.com/how-to-get-scheduling-page-links-for-team-members-across-the-organization ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Share meeting links How to get scheduling page links for team members across the organization (for admins) ====================================================================================== Access information about event types across the organization when you use an owner or admin generated personal access token. For example, sales leaders can give prospects access to the scheduling page links of specific account executives and customer success leaders can give clients access to their specific account managers. To get scheduling page links to event types across the organization --- Use the procedure below to access the event types across and organization using either required query parameter `organization` or `user` URI. 1. [Generate the personal access token](/how-to-authenticate-with-personal-access-tokens) using either an Owner or Admin’s Calendly account.. 2. Get and copy the organization or user URI (see [how to find the organization and user URI](/how-to-find-the-organization-or-user-uri).) 3. Replace `{access_token}` with your owner or admin generated personal access token. 4. To get all links to event types across the organization, make GET request to the `/event_types` [endpoint](/api-docs/b3A6NTkxNDEz-list-user-s-event-types) using the `organization` scope. Example request: curl --request GET \\   --url 'https://api.calendly.com/event\_types?organization={organization \_uri}' \\   --header 'authorization: Bearer {access_token}' 5. To get links to event types for a specific user, make a GET request to the `/event_types` [endpoint](/api-docs/b3A6NTkxNDEz-list-user-s-event-types) using the `user` scope. Example request: curl --request GET \\ \--url 'https://api.calendly.com/event\_types?user={user \_uri}' \\   --header 'authorization: Bearer {access_token}' Review the response payload --- Along with other information about the event, the response payload will include: - the `scheduling_uri` value that you can distribute out or add to your product so invitees can schedule a time with a team member - the `pooling_type` value which will indicate the event type such as a `round robin` or `collective` so you can understand what kind of event type you’re sharing. If it's not an event type with pooling capability, then the value will show as `null`. What's next --- [How to track and report on all scheduled events across your organization (admins only)](/track-and-report-on-all-scheduled-events-across-your-organization) [How to find the organization or user URI](/how-to-find-the-organization-or-user-uri) --- ---- url: https://developer.calendly.com/how-to-migrate-from-api-v1-to-api-v2 ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Migrate from API v1 to v2 How to migrate from API v1 to API v2 ==================================== Support for V1 API and Webhooks will begin phasing out in May 2025. While still supported until then, we do not recommend using API v1, webhooks created using API v1, or apps integrated using the API key on your [integrations page](https://calendly.com/integrations). ### The benefits of API v2 API v2 lets you seamlessly integrate Calendly into your product so you can put your data to work and enhance your productivity. You can retrieve Calendly links, sync scheduled meetings, manage users, and much more. When you migrate to API v2, you’ll appreciate: - A more secure way to connect and retrieve customers' data via OAuth 2.0 - Additional endpoints to support more [use cases](/api-use-cases), such as: - Managing your organization with admin level permissions - Becoming data compliant - Retrieving detailed information about scheduled events and invitees - Looking up information for all event types for all members in your organization - [Partnership opportunities](https://calendly.com/partners) with Calendly To migrate --- 1. If you are currently using the API v1 or webhooks for personal use or your internal applications, you can use a personal access token to make calls to API v2 (see [how to create a personal access token](/how-to-authenticate-with-personal-access-tokens).) Note: API v2 is not backwards compatible with API v1 so the data structure for API v2 responses does not match the API v1 payload. Please refer to the [API v2 documentation](/api-docs/ZG9jOjE1MDE3NzI-api-conventions) to see more details about each endpoint. 2. If you are currently using API v1 for a public application that many Calendly users will use or want to integrate a new one, [authenticate with OAuth](/create-a-developer-account). 1. When using OAuth, your users will authenticate into the OAuth Calendly application. 2. To ensure that there’s no lapse in service, you can continue using the API v1 until all of your app’s users authenticate into your OAuth application. Once they authenticate, make a call to the API v2 to confirm that you get a successful response. If you have questions, please reach out to developer support at [support+developer@calendly.com](mailto:support+developer@calendly.com). --- ---- url: https://developer.calendly.com ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) [Log in / Sign up](https://developer.calendly.com/login?origin=https://developer.calendly.com/console/apps) Now Available: Calendly MCP --------------------------- You can now build Calendly-powered conversational scheduling into your AI apps with the Calendly MCP server. [Get started.](https://developer.calendly.com/calendly-mcp-server) Create powerful apps with Calendly's API ======================================== Explore our documentation to start building custom integrations [Get started](/getting-started) Integrate to save time and deliver insights [See all the possibilities](/api-use-cases) [Automate your processes](/trigger-automations-with-other-apps-when-invitees-schedule-or-cancel-events) Automate next steps within your product based on scheduled events [Learn more](/trigger-automations-with-other-apps-when-invitees-schedule-or-cancel-events) [Embed Calendly on your site](/how-to-display-the-scheduling-page-for-users-of-your-app) Share your availability in an instant by adding Calendly to your favorite tools [Learn more](/how-to-display-the-scheduling-page-for-users-of-your-app) [Put your data to work](/track-and-report-on-all-scheduled-events-across-your-organization) Pull your scheduling report to better understand how your team uses meetings [Learn more](/track-and-report-on-all-scheduled-events-across-your-organization) [Share links from your product](/how-to-get-scheduling-page-links-for-team-members-across-the-organization) Share your and your team’s meeting links directly from your product [Learn more](/how-to-get-scheduling-page-links-for-team-members-across-the-organization) "Using the Calendly APIs and associated documentation, we were able to build and launch an integration quickly—an integration that continues to grow in popularity, bringing additional automation capabilities to Calendly." Shay Howe, SVP Platform Strategy, ActiveCampaign * * * Easyahead Solutions* [Sales](https://calendly.com/solutions/sales) * [Recruiting](https://calendly.com/solutions/recruiting) * [Customer Success](https://calendly.com/solutions/customer-success) * [Education](https://calendly.com/solutions/education) * [Integrations](https://calendly.com/integration) Resources* [Help Center](https://help.calendly.com/hc/en-us) * [Video Tutorials](https://help.calendly.com/hc/en-us/p/video-tutorials) * [Partner with us](https://calendly.com/partners) * [Developer Community](https://community.calendly.com/developer-community-60) About* [Calendly](https://calendly.com/about) * [Careers](https://careers.calendly.com/) * [Security](https://calendly.com/security) * [Developer Policy](/developer-policy) Copyright Calendly 2026We take the work out of connecting with others so you can accomplish more.[Legal](https://calendly.com/legal) ---- url: https://developer.calendly.com/enable-users-to-create-new-calendly-accounts-without-leaving-your-app ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Enable users to create new Calendly accounts without leaving your app Enable users to create new Calendly accounts without leaving your app --- Eliminate the drop offs that usually happen when your users are redirected from your app to sign up for a software that you’re integrated with. By implementing OAuth 2.0, you can enable Calendly's new user sign up flow in your app so your users can sign up for a Calendly account without leaving it. To get started, [create a Calendly developer account](/create-a-developer-account) --- ---- url: https://developer.calendly.com/frequently-asked-questions ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Frequently Asked Questions Frequently Asked Questions ========================== #### What Calendly subscription do I need to use the API? Developers can make GET and POST requests to API endpoints on behalf of a Calendly user on any subscription plan, including the Free plan (with the exception of a few endpoints that are specific to our Enterprise plan). The Enterprise-specific endpoints are: - [List activity entry logs](/api-docs/d37c7f031f339-list-activity-log-entries) - [Delete invitee data](/api-docs/4cf896120a018-delete-invitee-data) - [Delete scheduled event data](/api-docs/fc9211ad9b551-delete-scheduled-event-data) As for webhooks, the Calendly user account for which the webhook subscription is being made will need a paid subscription on the Standard, Teams, or Enterprise plan. You can read more about the features of each subscription on [our pricing page](https://calendly.com/pricing). For the v2 API, the developer's account is not connected to their Calendly account even if the same email address is utilized.  #### Can I schedule an event through the API? Yes, you can use the [Scheduling API](/api-docs/p3ghrxrwbl8kqe-create-event-invitee) to schedule Calendly meetings directly from your apps, workflows, or AI assistants. #### Can I cancel or reschedule an event through the API? Yes, to cancel an event via the API, you can send a POST request to the [cancel event](/api-docs/b3A6NDIzMTg0NDc-cancel-event) endpoint. At this time, there is no API endpoint that supports rescheduling an event or invitee, however the cancel and reschedule URLs are on the [invitee resource](/api-docs/b3A6NTkxNDE1-get-event-invitee). However, the cancel and reschedule URLs can be found on the v2 API webhook payload as well. You can see an example of the [payload here](/api-docs/c2NoOjIxNDU0NTQ2-webhook-payload). These URLs are always inserted at the bottom of calendar events or email confirmations, but they are available on the API to be more easily retrievable so you can place them wherever you want in the app that you are building. Please note that cancel event endpoint can be used to cancel an event, including a Group event, but not an individual invitee in a Group event. #### Can I update my schedule or availability through the API? Yes, you can update an Event Type’s availability by calling the  [Update Event Type Availability Schedules](/api-docs/twl2b8iuml1nz-update-event-type-availability-schedules) endpoint. #### Can I create or manage an event type through the API? Yes, you can do both with the [Create Event Type](/api-docs/nuowpx7qfagsc-create-event-type) or [Update Event Type](/api-docs/44f6bf7d769c8-update-event-type) endpoints. #### How do I get my Organization or User URI? Using either OAuth or personal access tokens, you can make a call to the [Get User API endpoint](/api-docs/b3A6Mzk2-get-user) or [Get Current User endpoint](/api-docs/005832c83aeae-get-current-user) to receive the user value on the uri and the organization value on the current_organization value on the response. If you are using OAuth with the v2 API, the user and organization URI is given in the payload of the [access token](/api-docs/b3A6NTkxNDA4-get-access-token) as the value of the owner and organization fields.  If you already know the user or organization URI, another way to get the values is to make a GET request to the [List Organization Memberships](/api-docs/eaed2e61a6bc3-list-organization-memberships) endpoint which returns a collection of all the Calendly members. In the user object of each collection, Calendly returns the user's organization URI.  Finally, in regards to the format of these values: URI format: https://api.calendly.com/organizations/012345678901234567890 - The authority: https://api.calendly.com - The path: organizations - The UUID: 012345678901234567890 #### Why is an organization URI required when using the user scope in webhook? An organization URI value is needed with a user-scoped webhook because a user can have multiple organizations associated with their data in Calendly, such as when they had their personal Calendly account before they were a member of an organization or after they leave an organization. As such, the organization is needed to confirm the specific user data that should be returned. #### What happens to a webhook subscription when the user is removed from the organization? If an administrator is removed from an organization, organization-scoped webhooks created by the removed administrator will continue to work. An administrator can delete organization-scoped webhooks created by another administrator using the [Delete Webhook Subscription endpoint](/api-docs/565b97f62dafe-delete-webhook-subscription). If a user is removed from an organization, user-scoped webhooks created by the removed user will no longer work. #### What happens to organization-scoped webhooks when the user's role changes from an Administrator to User? If a user's role changes from an administrator to a user, organization-scoped webhooks will continue to work and will remain scoped to the organization. #### How do I get additional invitee information that is not included in the webhook payload? The v2 API webhook payload provides a JSON object as seen [here](/api-docs/c2NoOjIxNDU0NTQ2-webhook-payload) in the documentation. Note that this object does not expose all of the invitee details. To get further details about the event, the webhook payload includes the invitee URI which can be used to make a GET request to the [Get Event Invitee endpoint](/api-docs/8305c0ccfac70-get-event-invitee) to expose additional invitee details. #### How long is a single-use scheduling link valid for?  Single use scheduling links (that haven’t been used to book an event) expire after 90 days. #### Can I retrieve information for a User that has been removed from the Organization? When a user is removed from the organization, they become a solo account. Events that were scheduled with the user while they were part of the organization are still associated with the organization. You will be able to see a removed user's events when you use the organization parameter when making a call to the [List Events](/api-docs/2d5ed9bbd2952-list-events) endpoint (using an access token associated with an Owner or Admin in the organization). Note that you will only see events that were scheduled when the user was part of the organization; any events scheduled with the solo account after removal will not be included. #### Can custom query parameters be passed into the booking page and retrieved via the API? Yes, to send unique or custom query parameters into your scheduled event, you can use UTM parameters on your scheduling link to pass in your custom data values. This data will be hidden from the booking flow, but will be visible on your URL.  When you add these to your scheduling URL, this data will then be associated with the event and available in [webhook payload](/api-docs/c2NoOjIxNDU0NTQ2-webhook-payload) (tracking) and when making a call to the [List Event Invitees](/api-docs/eb8ee72701f99-list-event-invitees) endpoint (tracking). More information about using UTM parameters can be found [right here](https://help.calendly.com/hc/en-us/articles/1500005575121). The UTM parameters are: utm_source, utm_medium, utm_campaign, utm_content, and utm_term. While these are typically used for tracking and conversion purposes, you're welcome to use other values in these such as a userID or anything else you need to track. For example: https://calendly.com/YOUR\_EVENT?utm\_source=12345&utm\_medium=Smith [This page](https://help.calendly.com/hc/en-us/articles/4406950779799) is also a great reference for passing UTM parameters specifically to a Calendly embed, if you are currently utilizing one of our [embed options](https://help.calendly.com/hc/en-us/articles/223147027-Embed-options-overview). #### What are the conditions that result in an access token being revoked? Both OAuth access tokens and personal access tokens can be revoked manually, but there are also certain conditions in the Calendly account that will cause the token to be revoked. Both OAuth and personal access tokens will be revoked if: - The account's login email is changed. - The account's password is changed. - The account's login method is changed.    Access tokens can also be revoked manually. OAuth access tokens can be revoked by submitting a POST request to the [revoke access/refresh token](/api-docs/b3A6MTg2OTAyNA-revoke-access-refresh-token) endpoint. Personal access tokens can be revoked by clicking 'Revoke' next to the token on the account's [API & Webhooks page](https://calendly.com/integrations/api_webhooks). --- ---- url: https://developer.calendly.com/schedule-events-with-ai-agents ---- [Developer](/) [Documentation](/getting-started)[API Reference](/api-docs)[Release Notes](/release-notes)[Support](/get-help) Schedule Events with AI Agents Schedule Events with AI Agents ============================== Enable AI assistants or agents in your product to book meetings end‑to‑end via Calendly’s Scheduling API endpoint. This guide covers how to programmatically leverage collected booking details to create a scheduled event using the Create Event Invitee endpoint. Use this pattern when you want automated booking inside a chat, workflow, or copilot experience without redirecting users to Calendly. This functionality will require an OAuth application in order to leverage the API on behalf of end-users. You can start by navigating to our developer portal here: [https://developer.calendly.com/](/) and logging in (button at the top right), followed by creating a Developer OAuth application. Find our documentation on our [OAuth applications here](/create-a-developer-account), and an example of an [OAuth implementation (BuzzwordCRM) here](https://github.com/calendly/buzzwordcrm). The host or admin of the Calendly account can also use a Personal Access Token to leverage the API for their respective Calendly organization. A personal access token can be generated on the following [Integration and Apps page](https://calendly.com/integrations/api_webhooks). How It Works ============ 1. Determine the event type (and/or host) to book (agent maps user intent -> event type / host). 2. Select a timeslot (via GET /event_type_available_times) 3. Create the invitee with POST /invitees, including event_type, start_time (UTC), and invitee details. 4. Return confirmation: show booking summary plus optionally display reschedule and cancel links. Key Endpoints --- - [GET /event_types](/api-docs/25a4ece03c1bc-list-user-s-event-types) OR [GET /event_types/{uuid}](/api-docs/c1f9db4a585da-get-event-type) Retrieve the entire organization or specific user’s/owner’s event types to map intent -> event type. - [GET /event_type_available_times](/api-docs/6a1be82aef359-list-event-type-available-times) Retrieve the appropriate event type available times to allow invitee to choose from.  - POST invitees Schedule a meeting by creating an invitee for a specific event/time. \*Base URL: https://api.calendly.com/{ENDPOINT} Common Use Cases --- - Conversational scheduling: After a short dialog, the agent proposes 2–3 times and books the selected slot. - Triage -> schedule: Bot determines the right user/event type (Sales/Success/Recruiting) and books. - Hands‑free follow‑ups: Agent books time and includes additional event guests as CCs. Steps to Implement --- The steps below assume you’ve configured your AI agent to collect the required and optional details to begin the scheduling flow. Considerations such as the reason for the meeting, their locale, preference on location, and duration can all be considered when finding an appropriate event type.  ### 1) Map Intent to Event Type Use your own rules or metadata to pick the right event type (e.g., “30‑min Demo” vs. “Onboarding Call”). Retrieve your organization/users event types using the /event_types endpoint.  ### 2) Select an Available Timeslot Pass the event type URI to retrieve a list of event type available times from the /event_type_available_times endpoint. Present availability to the end‑user and collect a chosen start time. Normalize to UTC with a trailing Z (e.g., 2025-10-02T18:30:00Z). ### 3) Create the Invitee (Book the Meeting) Endpoint: POST [https://api.calendly.com/invitees](https://api.calendly.com/invitees) Important Considerations: The Location Object representing the meeting location. This is required unless the Event Type does not specify a location, in which case it must be omitted.  When included, it must contain location.kind.  If the location.kind defined by the host could require invitee input (such as ask_invitee, outbound_call, or if multiple custom or physical locations exist), the invitee must provide the corresponding details in location.location. Minimum request body: { "event_type": "https://api.calendly.com/event\_types/AAAAAAAAAAAAAA", "start_time": "2019-08-07T06:05:04.321123Z", "invitee": { "name": "John Smith", "first\_name": "John", "last\_name": "Smith", "email": "test@example.com", "timezone": "America/New\_York" }, "location": { "kind": "zoom\_conference" } } Optional fields (popular): - event_guests: array of additional email addresses to include on the event - questions_and_answers: \[ { "question": "Company", "answer": "Acme", "position": 1 } \] - tracking: utm_source, utm_campaign, utm_medium, utm_content, utm_term, salesforce_uuid - invitee.text_reminder_number: E.164 phone for SMS reminders (when configured as a question on the event type) cURL example: curl -X POST "https://api.calendly.com/invitees" \\ -H "Authorization: Bearer $ACCESS_TOKEN" \\ -H "Content-Type: application/json" \\ -d '{ "event\_type": "https://api.calendly.com/event\_types/AAAAAAAAAAAAAAAA", "start\_time": "2025-10-02T18:30:00Z", "invitee": { "name": "Jordan Lee", "email": "jordan@example.com", "timezone": "America/New\_York" }, "event\_guests": \["alex@example.com"\], "tracking": {"utm\_source": "agent", "utm\_campaign": "pilot"} }' Response highlights: - event (scheduled event URI), status, timezone - cancel_url, reschedule_url - questions_and_answers, text_reminder_number - Lifecycle: created_at, updated_at; reschedule metadata (rescheduled, old_invitee, new_invitee) ### 5) Show Confirmation + Management Links Confirm the booking in the user’s local timezone and optionally provide Cancel/Reschedule actions powered by the returned URLs. Example: Book a 30‑Minute Demo via Agent --- 1. User: “Book a 30‑minute demo with Taylor next week, afternoons only.” 2. Agent: Maps intent -> event type URI for “30‑minute demo” for the user Taylor. 3. Agent: Retrieve event type available times using the event type URI 4. Agent: Offers Wed/Thu 2:30–4:30pm slots; user picks Thu 3:00pm ET. 5. Backend: POST /invitees with the chosen UTC start time and invitee info. 6. UI: Shows success state with reschedule/cancel links. 7. Invitation and other respective text/email notifications fire based on configurations set in the event type settings. General Limitations & Considerations ==================================== - Subscription Tier: Calendly customers are required to be on a paid plan in order to access or use applications calling the Scheduling API. - Timeslot accuracy: start_time must correspond to a valid open slot at booking time. - Location selection: The Location Object representing the meeting location. This is required unless the Event Type does not specify a location, in which case it must be omitted.  When included, it must contain location.kind.  If the location.kind defined by the host could require invitee input (such as ask_invitee, outbound_call, or if multiple custom or physical locations exist), the invitee must provide the corresponding details in location.location. Make note of our [documentation pages](/api-docs/p3ghrxrwbl8kqe-create-event-invitee) for location kind and location parameters based on the location option. - Event_type_available_times 7-day limit: this endpoint can only retrieve 7 days of available times per request. You may poll this endpoint at different 7 day intervals. - Timezone rules: Use IANA timezones (e.g., America/New_York) and convert display times accordingly. - Validation: Validate emails; consider common typos; avoid booking without user confirmation. Error Handling Cheatsheet ========================= - Validation error (missing or invalid field) - Status - 400 - Show actionable error; re‑collect inputs - Unauthorized token - Status - 401 - Refresh token or re‑authenticate - Forbidden (policy or scope) - Status - 403 - Route to human or request elevated permissions - Not found (event type or time slot) - Status - 404 - Re‑query availability and propose alternatives - Transient server issue - Status - 5xx - Retry with backoff; show friendly fallback QA / UAT Checklist ================== - Booking succeeds with minimal fields (name, email, timezone, UTC start_time) - Returned reschedule/cancel links are visible and functional in your UI - Timezone verified across confirmation methods (emails/UI) - event_guests honored (when provided) - tracking fields reach downstream reporting/CRM - Logs redact PII; errors are user‑friendly and specific --- Easyahead Solutions\* [Sales](https://calendly.com/solutions/sales) - [Recruiting](https://calendly.com/solutions/recruiting) - [Customer Success](https://calendly.com/solutions/customer-success) - [Education](https://calendly.com/solutions/education) - [Integrations](https://calendly.com/integration) Resources\* [Help Center](https://help.calendly.com/hc/en-us) - [Video Tutorials](https://help.calendly.com/hc/en-us/p/video-tutorials) - [Partner with us](https://calendly.com/partners) - [Developer Community](https://community.calendly.com/developer-community-60) About\* [Calendly](https://calendly.com/about) - [Careers](https://careers.calendly.com/) - [Security](https://calendly.com/security) - [Developer Policy](/developer-policy) Copyright Calendly 2026We take the work out of connecting with others so you can accomplish more.[Legal](https://calendly.com/legal)