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 Basic plan (with the exception of a few endpoints that are specific to our Enterprise plan).

The Enterprise-specific endpoints are:

• List activity entry logs

• Delete invitee data

• 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 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. 

Can I schedule an event through the API?

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.

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 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.

Can I update my schedule or availability through the API?

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.

Can I create or manage an event type through the API?

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.

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 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

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.

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 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 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 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 (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.

For example:

https://calendly.com/YOUR_EVENT?utm_source=12345&utm_medium=Smith

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.

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 endpoint. Personal access tokens can be revoked by clicking 'Revoke' next to the token on the account's API & Webhooks page.