How to setup API in a local instance

Cal.com Docs

Introduction

Local Development

Code styling

Pull requests

Contributor's Guide

Installation

Database migrations

Upgrading

SSO setup

Docker

License key

Azure

Elestio

Railway

Render

Vercel

Get started with creating a platform account

Setup

Find out how to use Cal "atoms" to integrate scheduling into your product.

Quickstart

Answers to the most common questions about the Platform API and atoms.

Introduction to API v2

Differences between v1 and v2

Get all managed users

Create a managed user

Get a managed user

Delete a managed user

Update a managed user

If you have lost managed user access or refresh token, then you can get new ones by using OAuth credentials. Access token is valid for 60 minutes and refresh token for 1 year. Make sure to store them in your database, for example, in your User database model `calAccessToken` and `calRefreshToken` fields.
Response also contains `accessTokenExpiresAt` and `refreshTokenExpiresAt` fields, but if you decode the jwt token the payload will contain `clientId` (OAuth client ID), `ownerId` (user to whom token belongs ID), `iat` (issued at time) and `expiresAt` (when does the token expire) fields.

Force refresh tokens

If managed user access token is expired then get a new one using this endpoint - it will also refresh the refresh token, because we use
    "refresh token rotation" mechanism. Access token is valid for 60 minutes and refresh token for 1 year. Make sure to store them in your database, for example, in your User database model `calAccessToken` and `calRefreshToken` fields.
Response also contains `accessTokenExpiresAt` and `refreshTokenExpiresAt` fields, but if you decode the jwt token the payload will contain `clientId` (OAuth client ID), `ownerId` (user to whom token belongs ID), `iat` (issued at time) and `expiresAt` (when does the token expire) fields.

Refresh managed user tokens

Get all webhooks

Create a webhook

Delete all webhooks

Get a webhook

Delete a webhook

Update a webhook

Get all attributes

Create an attribute

Get an attribute

Delete an attribute

Update an attribute

Get all attribute options

Create an attribute option

Delete an attribute option

Update an attribute option

Get by attribute id all of the attribute options that are assigned to users

Get by attribute slug all of the attribute options that are assigned to users

Get all attribute options for a user

Assign an attribute to a user

Unassign an attribute from a user

Get Organization Bookings

Save delegation credentials for your organization.

Update delegation credentials of your organization.

Get all memberships

Create a membership

Get a membership

Delete a membership

Update a membership

Get organization routing forms

Get routing form responses

Update routing form response

Get all schedules

Get all teams

Create a team

Get teams membership for user

Get a team

Delete a team

Update a team

Get organization team bookings

Get 'Booking References' for a booking

Connect your conferencing application to a team

Get OAuth conferencing app's auth url for a team

List team conferencing applications

Set team default conferencing application

Get team default conferencing application

Disconnect team conferencing application

Save conferencing app OAuth credentials

Get team event types

Create an event type

Get an event type

Delete a team event type

Update a team event type

Create a phone call

Get all team event types

Get team routing forms

Get organization team routing form responses

Get schedules of a team member

Get all users

Create a user

Delete a user

Update a user

Get all bookings of an organization user

Get all ooo entries of a user

Create an ooo entry for user

Delete ooo entry of a user

Update ooo entry of a user

Get all OOO entries of org users

Create a schedule

Get a schedule

Delete a schedule

Update a schedule

Generate a new API key and delete the current one. Provide API key to refresh as a Bearer token in the Authorization header (e.g. "Authorization: Bearer <apiKey>").

Refresh API Key

Get all bookings


      POST /v2/bookings is used to create regular bookings, recurring bookings and instant bookings. The request bodies for all 3 are almost the same except:
      If eventTypeId in the request body is id of a regular event, then regular booking is created.

      If it is an id of a recurring event type, then recurring booking is created.

      Meaning that the request bodies are equal but the outcome depends on what kind of event type it is with the goal of making it as seamless for developers as possible.

      For team event types it is possible to create instant meeting. To do that just pass `"instant": true` to the request body.

      The start needs to be in UTC aka if the timezone is GMT+2 in Rome and meeting should start at 11, then UTC time should have hours 09:00 aka without time zone.

      Finally, there are 2 ways to book an event type belonging to an individual user:
      1. Provide `eventTypeId` in the request body.
      2. Provide `eventTypeSlug` and `username` and optionally `organizationSlug` if the user with the username is within an organization.

      And 2 ways to book and event type belonging to a team:
      1. Provide `eventTypeId` in the request body.
      2. Provide `eventTypeSlug` and `teamSlug` and optionally `organizationSlug` if the team with the teamSlug is within an organization.
      

Create a booking

`:bookingUid` can be

      1. uid of a normal booking

      2. uid of one of the recurring booking recurrences

      3. uid of recurring booking which will return an array of all recurring booking recurrences (stored as recurringBookingUid on one of the individual recurrences).

Get a booking

Reschedule a booking

:bookingUid can be :bookingUid of an usual booking, individual recurrence or recurring booking to cancel all recurrences.
    For seated bookings to cancel one individual booking provide :bookingUid and :seatUid in the request body. For recurring seated bookings it is not possible to cancel all of them with 1 call
    like with non-seated recurring bookings by providing recurring bookind uid - you have to cancel each recurrence booking by its bookingUid + seatUid.

Cancel a booking

The provided authorization header refers to the owner of the booking.

Mark a booking absence

Currently only supports reassigning host for round robin bookings. The provided authorization header refers to the owner of the booking.

Reassign a booking to auto-selected host

Reassign a booking to a specific host

Confirm a booking

Decline a booking

Retrieve calendar links for a booking that can be used to add the event to various calendar services. Returns links for Google Calendar, Microsoft Office, Microsoft Outlook, and a downloadable ICS file.

Get 'Add to Calendar' links for a booking

Save an ICS feed

Check an ICS feed

Get busy times from a calendar. Example request URL is `https://api.cal.com/v2/calendars/busy-times?loggedInUsersTz=Europe%2FMadrid&dateFrom=2024-12-18&dateTo=2024-12-18&calendarsToLoad[0][credentialId]=135&calendarsToLoad[0][externalId]=skrauciz%40gmail.com`

Get busy times

Get all calendars

Get oAuth connect URL

Save Google or Outlook calendar credentials

Save Apple calendar credentials

Check a calendar connection

Disconnect a calendar

Connect your conferencing application

Get OAuth conferencing app auth url

conferencing apps oauths callback

List your conferencing applications

Set your default conferencing application

Get your default conferencing application

Disconnect your conferencing application

Update destination calendars

Get all event types

Delete an event type

Update an event type

Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.

Get all organizations within an organization

Create an organization within an organization

Get an organization within an organization

Delete an organization within an organization

Update an organization within an organization

Get my profile

Update my profile

Get all OAuth clients

Create an OAuth client

Get an OAuth client

Delete an OAuth client

Update an OAuth client

Request Email Verification Code

Sends a verification code to the phone number.

Request Phone Number Verification Code

Verify an email for an org team.

Verify a phone number for an org team.

Get list of verified emails of an org team.

Get list of verified phone numbers of an org team.

Get verified email of an org team by id.

Get verified phone number of an org team by id.

Get stripe connect URL for a team

Check team stripe connection

Save stripe credentials

It will not actually save the response just return the routed event type and slots when it can be booked.

Calculate slots based on routing form response

Get all schedules of the authenticated user.


      Create a schedule for the authenticated user.

      The point of creating schedules is for event types to be available at specific times.

      The first goal of schedules is to have a default schedule. If you are platform customer and created managed users, then it is important to note that each managed user should have a default schedule.
      1. If you passed `timeZone` when creating managed user, then the default schedule from Monday to Friday from 9AM to 5PM will be created with that timezone. The managed user can then change the default schedule via the `AvailabilitySettings` atom.
      2. If you did not, then we assume you want the user to have this specific schedule right away. You should create a default schedule by specifying
      `"isDefault": true` in the request body. Until the user has a default schedule the user can't be booked nor manage their schedule via the AvailabilitySettings atom.

      The second goal of schedules is to create another schedule that event types can point to. This is useful for when an event is booked because availability is not checked against the default schedule but instead against that specific schedule.
      After creating a non-default schedule, you can update an event type to point to that schedule via the PATCH `event-types/{eventTypeId}` endpoint.

      When specifying start time and end time for each day use the 24 hour format e.g. 08:00, 15:00 etc.
      

Get the default schedule of the authenticated user.

Get default schedule

Add a selected calendar

Delete a selected calendar


      There are 4 ways to get available slots for event type of an individual user:

      1. By event type id. Event type id can be of user and team event types. Example '/v2/slots?eventTypeId=10&start=2050-09-05&end=2050-09-06&timeZone=Europe/Rome'

      2. By event type slug + username. Example '/v2/slots?eventTypeSlug=intro&username=bob&start=2050-09-05&end=2050-09-06'

      3. By event type slug + username + organization slug when searching within an organization. Example '/v2/slots?organizationSlug=org-slug&eventTypeSlug=intro&username=bob&start=2050-09-05&end=2050-09-06'

      4. By usernames only (used for dynamic event type - there is no specific event but you want to know when 2 or more people are available). Example '/v2/slots?usernames=alice,bob&username=bob&organizationSlug=org-slug&start=2050-09-05&end=2050-09-06'. As you see you also need to provide the slug of the organization to which each user in the 'usernames' array belongs.

      And 3 ways to get available slots for team event type:

      1. By team event type id. Example '/v2/slots?eventTypeId=10&start=2050-09-05&end=2050-09-06&timeZone=Europe/Rome'

      2. By team event type slug + team slug. Example '/v2/slots?eventTypeSlug=intro&teamSlug=team-slug&start=2050-09-05&end=2050-09-06'

      3. By team event type slug + team slug + organization slug when searching within an organization. Example '/v2/slots?organizationSlug=org-slug&eventTypeSlug=intro&teamSlug=team-slug&start=2050-09-05&end=2050-09-06'

      All of them require "start" and "end" query parameters which define the time range for which available slots should be checked.
      Optional parameters are:
      - timeZone: Time zone in which the available slots should be returned. Defaults to UTC.
      - duration: Only use for event types that allow multiple durations or for dynamic event types. If not passed for multiple duration event types defaults to default duration. For dynamic event types defaults to 30 aka each returned slot is 30 minutes long. So duration=60 means that returned slots will be each 60 minutes long.
      - format: Format of the slots. By default return is an object where each key is date and value is array of slots as string. If you want to get start and end of each slot use "range" as value.
      

Find out when is an event type ready to be booked.

Make a slot not available for others to book for a certain period of time. If you authenticate using oAuth credentials, api key or access token
    then you can also specify custom duration for how long the slot should be reserved for (defaults to 5 minutes).

Getting Started

Open Source Contribution

Guides

How to setup API in a local instance