Cal.com Docs

Developing

Self Hosting

Platform

API v2 Reference

API v1 Reference

Dashboard

Support

Find a booking reference

ApiKeyAuth

Introduction

Local Development

Code styling

Pull requests

Contributor's Guide

How to setup API in a local instance

Build a greeter app

How to build an app

Assign people to a call from a CRM or database

How to use OAuth to authorize apps with Cal.com accounts

Setting up OIDC with okta

SSO setup

Webhooks

Setting up mailtrap for email testing

Embed Events

Installation

Database migrations

Upgrading

Docker

License key

Azure

Elestio

Railway

Render

Vercel

Google

Microsoft

Zoom

Daily

HubSpot

Sendgrid

Stripe

Twilio

Zoho

How to sync third party apps

How to white label the self hosted instance

How to add custom CSS

Instance-wide theming using color tokens

Can Cal.com sponsor my open source project?

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

Quickstart

Google calendar connect

Outlook calendar connect

Apple calendar connect

Availability settings

Booker

Event Type

Calendar settings

Payment form

Conferencing Apps

Replace default cal.com toasts with your own

Custom toasts

Prefilling and / or making them read-only.

Managing booking fields

Booking redirects

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

Introduction to API v2

Differences between v1 and v2

Quick start

Authentication

Errors

Rate limits

Get a provider

Verify an access token

Get auth URL

Connect a calendar

Check a calendar connection status

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 schedules of a team member

Get all users

Create a user

Delete a user

Update a user

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

Save a calendar

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.
      

Getting Started

Attendees

Availabilities

Booking References

Bookings

Credentials

Destination Calendars

Event Types

Memberships

Payments

Schedules

Selected Calendars

slots

Teams

Users

Webhooks

Find a booking reference

Authorizations

Path Parameters

Query Parameters