Calendly logoCalendly logo
Developer

How to migrate from API v1 to API v2

API v1 and webhooks will phase out by June 30, 2022. 

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. If you still need to integrate an app with API v1, ensure that the app on another platform makes an API key a requirement to integrate with Calendly. If an API key is not mandatory, integrate your app with API v2.

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

    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.