Developers can make GET and POST requests to API endpoints on behalf of a Calendly user on any subscription plan, including the Basic plan (with the exception of a few endpoints that are specific to our Enterprise plan).
The Enterprise-specific endpoints are:
As for webhooks, the Calendly user account for which the webhook subscription is being made will need a paid subscription on the Professional, Teams, or Enterprise plan. You can read more about the features of each subscription on our pricing page.
For the v2 API, the developer's account is not connected to their Calendly account even if the same email address is utilized.
At this time, our API endpoints do not support scheduling events. To schedule an event from your website, you can use one of our embed options.
Yes, to cancel an event via the API, you can send a POST request to the 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.
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.
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.
At this time, our API endpoints do not support setting or managing availability. To set availability, users will need to visit their Event Types page within their Calendly account.
At this time, our API endpoints do not support creating or managing event types. To manage an event or event type, users will need to visit their Event Types page within their Calendly account.
Using either OAuth or personal access tokens, you can make a call to the Get User API endpoint or Get Current User endpoint 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 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 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
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.
The v2 API webhook payload provides a JSON object as seen here in the documentation. Note that this object does not expose all of the event details. To get further details about the event, the webhook payload includes the event URI which can be used to make a GET request to the Get Event endpoint to expose the event's details. The webhook payload also includes the invitee URI which can be used to make a GET request to the Get Event Invitee endpoint to expose additional invitee details.
Single use scheduling links (that haven’t been used to book an event) expire after 90 days.
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 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.
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 (
tracking) and when making a call to the List Event Invitees endpoint (
tracking). More information about using UTM parameters can be found right here.
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.
This page is also a great reference for passing UTM parameters specifically to a Calendly embed, if you are currently utilizing one of our embed options.
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 endpoint. Personal access tokens can be revoked by clicking 'Revoke' next to the token on the account's API & Webhooks page.