Find a team

ApiKeyAuth

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

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

Verify an access token

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.
    Each access token is valid for 60 minutes and each refresh token for 1 year. Make sure to store them later in your database, for example, by updating the User model to have `calAccessToken` and `calRefreshToken` columns.

Force refresh tokens

If managed user access token is expired then get a new one using this endpoint. Each access token is valid for 60 minutes and 
    each refresh token for 1 year. Make sure to store them later in your database, for example, by updating the User model to have `calAccessToken` and `calRefreshToken` columns.

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 all attribute options for a user

Assign an attribute to a user

Unassign an attribute from a user

Get a team event type

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

Create a membership

Get a membership

Delete a membership

Update a membership

Get all schedules

Create a schedule

Get a schedule

Delete a schedule

Update a schedule

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 routing form responses

Get schedules of a team member

Get all users

Create a user

Delete a user

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

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.
      

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 by passing `:bookingUid` of the booking that should be rescheduled and pass request body with a new start time to create a new 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

Mark a booking absence

Automatically reassign booking to a new host

Reassign a booking to a specific user

Confirm booking that requires a confirmation

Decline booking that requires a confirmation

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 an oAuth calendar credentials

Sync 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

Get my profile

Update my profile

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

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

Reserve a slot

Get reserved slot

Delete v2slotsreservations

Updated reserved a slot

Get stripe connect URL

Save stripe credentials

Check stripe connection

Check team stripe connection

Get teams

Get all timezones

Gets a paginated list of webhooks for the authenticated user.

Get all webooks

Quick start

Authentication

Errors

Rate limits

Find all attendees

Creates a new attendee

Find an attendee

Remove an existing attendee

Edit an existing attendee

Creates a new availability

Find an availability

Remove an existing availability

Edit an existing availability

Find all booking references

Creates a new  booking reference

Find a booking reference

Remove an existing booking reference

Edit an existing booking reference

Creates a new booking

Booking cancellation

Find a booking

Edit an existing booking

Find all Cal video recordings of that booking

Find all Cal video transcripts of that booking

Find all Cal video transcripts of that recording

Get all app credentials for a user

Create a credential record for a user

Delete a credential record for a user

Update a credential record for a user

Find all destination calendars

Creates a new destination calendar

Find a destination calendar

Remove an existing destination calendar

Edit an existing destination calendar

Find all event types

Creates a new event type

Find a eventType

Remove an existing eventType

Edit an existing eventType

Find all event types that belong to teamId

Find all memberships

Creates a new membership

Find a membership by userID and teamID

Remove an existing membership

Edit an existing membership

Find a payment

Find all payments

Find all schedules

Creates a new schedule

Find a schedule

Remove an existing schedule

Edit an existing schedule

Find all selected calendars

Creates a new selected calendar

Find a selected calendar by providing the compoundId(userId_integration_externalId) separated by `_`

Getting Started

Attendees

Availabilities

Booking References

Bookings

Credentials

Destination Calendars

Event Types

Memberships

Payments

Schedules

Selected Calendars

slots

Teams

Users

Webhooks

Find a team

Authorizations

Path Parameters

Query Parameters