Skip to main content
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 CodeDescription
200Success - Request completed successfully
201Created - Resource created successfully
400Bad Request - Invalid request parameters
401Unauthorized - Invalid or missing authentication
403Forbidden - Insufficient permissions
404Not Found - Resource not found
429Too Many Requests - Rate limit exceeded
500Internal 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

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: '[email protected]'
  }
});

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

Build docs developers (and LLMs) love

Get started for freeTalk to us