Platform API Introduction

Build powerful scheduling integrations with Cal.com’s Platform API v2

The Cal.com Platform API v2 provides a comprehensive REST API for building scheduling applications and integrations. It enables you to programmatically manage bookings, event types, users, webhooks, and more.

Base URL

All API requests should be made to:

https://api.cal.com/v2

API Versioning

The Platform API uses date-based versioning to ensure backward compatibility. Current supported versions:

• 2024-08-13 - Latest version with enhanced booking features
• 2024-06-14 - Extended booking management
• 2024-06-11 - Additional booking endpoints
• 2024-04-15 - Core booking API

Specify the API version using the cal-api-version header:

curl -X GET https://api.cal.com/v2/bookings \
  -H "Authorization: Bearer cal_live_<your_api_key>" \
  -H "cal-api-version: 2024-08-13"

Core Features

Bookings Management

Create, retrieve, update, and cancel bookings programmatically

Event Types

Manage event types with custom availability and settings

Webhooks

Receive real-time notifications for booking events

OAuth 2.0

Secure authentication for third-party applications

Key Endpoints

Bookings

GET    /v2/bookings              # List bookings
GET    /v2/bookings/:bookingUid  # Get booking details
POST   /v2/bookings              # Create a booking
POST   /v2/bookings/:bookingUid/cancel  # Cancel booking
POST   /v2/bookings/recurring    # Create recurring booking

Event Types

GET    /v2/event-types           # List event types
GET    /v2/event-types/:id       # Get event type
POST   /v2/event-types           # Create event type
PATCH  /v2/event-types/:id       # Update event type
DELETE /v2/event-types/:id       # Delete event type

Webhooks

GET    /v2/webhooks              # List webhooks
POST   /v2/webhooks              # Create webhook
PATCH  /v2/webhooks/:webhookId   # Update webhook
DELETE /v2/webhooks/:webhookId   # Delete webhook

Response Format

All API responses follow a consistent structure:

{
  "status": "success",
  "data": {
    // Response data
  }
}

Success Response

{
  "status": "success",
  "data": {
    "id": 123,
    "title": "30 Minute Meeting",
    "startTime": "2024-03-15T10:00:00Z"
  }
}

Error Response

{
  "status": "error",
  "error": {
    "message": "Booking not found",
    "code": "NOT_FOUND"
  }
}

HTTP Status Codes

Status Code	Description
200	Success - Request completed successfully
201	Created - Resource created successfully
400	Bad Request - Invalid request parameters
401	Unauthorized - Invalid or missing authentication
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error

Request Headers

Required Headers

Authorization: Bearer cal_live_<your_api_key>
Content-Type: application/json

Optional Headers

cal-api-version: 2024-08-13        # API version
X-Cal-Client-ID: <client_id>       # OAuth client ID
X-Request-Id: <unique_id>          # Request tracking ID

Pagination

List endpoints support cursor-based pagination:

GET /v2/bookings?limit=10&cursor=0

Parameters:

• limit - Number of results per page (default: 10, max: 250)
• cursor - Pagination cursor (offset)

Response:

{
  "status": "success",
  "data": {
    "bookings": [...],
    "nextCursor": 10,
    "totalCount": 45
  }
}

Filtering

Many endpoints support filtering:

GET /v2/bookings?filters[status]=upcoming
GET /v2/bookings?filters[eventTypeId]=123

Platform Features

Managed Users

Create and manage users programmatically:

POST /v2/organizations/:orgId/users

Team Management

GET  /v2/teams
POST /v2/teams/:teamId/memberships

OAuth Clients

GET /v2/oauth-clients

SDK Libraries

TypeScript

import { CalComAPI } from '@calcom/api-client';

const cal = new CalComAPI({
  apiKey: 'cal_live_xxxxx'
});

const booking = await cal.bookings.create({
  eventTypeId: 123,
  start: '2024-03-15T10:00:00Z',
  responses: {
    name: 'John Doe',
    email: '[e-mail]'
  }
});

Getting Started

1. Get API Credentials

   Generate an API key or set up OAuth 2.0 authentication

2. Make Your First Request

   Test the API with a simple GET request to list bookings

3. Set Up Webhooks

   Configure webhooks to receive real-time event notifications

4. Build Your Integration

   Use the full API to build your scheduling application

Next Steps

Authentication

Learn about API keys and OAuth 2.0

Webhooks

Set up real-time event notifications

Rate Limits

Understand rate limiting policies

OAuth 2.0 Guide

Implement OAuth 2.0 flows

Support

Need help? Here are some resources:

• API Reference: Detailed endpoint documentation
• GitHub: github.com/calcom/cal.com
• Community: cal.com/slack
• Email: [e-mail]