Migrating from V1 to V2

This guide will help you migrate your integration from Cal.com API V1 to V2. The V2 API offers improved performance, enhanced security, better response objects, and new features that make it easier to build powerful integrations.

Why migrate to V2?

• Better performance: Optimized for speed and scalability
• Enhanced security: Improved authentication methods and security measures
• User-friendly responses: Cleaner, more consistent response objects
• New features: Access to organization management, and more

Authentication changes

V1 authentication

In V1, you authenticated using an API key in the query string:

curl https://api.cal.com/v1/event-types?apiKey=cal_test_xxxxxx

V2 authentication

In V2, authentication uses header-based API keys for improved security:

curl https://api.cal.com/v2/event-types \
  -H "Authorization: Bearer cal_live_xxxxxx"

Base URL changes

Endpoint mapping

Bookings

V1 example:

DELETE /v1/bookings/123?apiKey=cal_test_xxx

V2 example:

POST /v2/bookings/cal_abc123/cancel
Authorization: Bearer cal_live_xxx
Content-Type: application/json

{
  "cancellationReason": "Schedule conflict"
}

Event types

Schedules

Users

Teams

Webhooks

Slots

New features in V2

Organization management

V2 introduces comprehensive organization endpoints for enterprise customers:

• GET /v2/orgs/teams - Manage organization teams
• GET /v2/orgs/users - Manage organization users
• GET /v2/orgs/bookings - View all organization bookings
• GET /v2/orgs/memberships - Manage team memberships
• GET /v2/orgs/roles - Manage custom roles and permissions

Enhanced booking management

• POST /v2/bookings/{uid}/confirm - Confirm pending bookings
• POST /v2/bookings/{uid}/decline - Decline booking requests
• POST /v2/bookings/{uid}/mark-absent - Mark no-shows
• POST /v2/bookings/{uid}/reassign - Reassign bookings to different hosts
• POST /v2/bookings/{uid}/guests - Add guests to existing bookings

Calendar integrations

• GET /v2/calendars - List connected calendars
• GET /v2/calendars/busy-times - Check availability across calendars
• POST /v2/calendars/connect - Connect calendar providers
• POST /v2/calendars/disconnect - Disconnect calendars

Conferencing apps

• GET /v2/conferencing - List conferencing apps
• POST /v2/conferencing/connect - Connect conferencing providers
• POST /v2/conferencing/set-default - Set default conferencing app

Response format changes

V1 response structure

{
  "booking": {
    "id": 123,
    "title": "Meeting",
    "startTime": "2024-01-15T10:00:00Z"
  }
}

V2 response structure

{
  "status": "success",
  "data": {
    "id": 123,
    "uid": "cal_abc123xyz",
    "title": "Meeting",
    "startTime": "2024-01-15T10:00:00.000Z",
    "endTime": "2024-01-15T11:00:00.000Z",
    "status": "accepted",
    "attendees": [...],
    "metadata": {...}
  }
}

Key improvements:

• Consistent status and data wrapper
• More detailed timestamps with milliseconds
• Additional metadata and context
• Better error messages with specific error codes

Error handling

V1 errors

{
  "message": "Event type not found"
}

V2 errors

{
  "status": "error",
  "error": {
    "code": "NOT_FOUND",
    "message": "Event type not found",
    "details": {
      "eventTypeId": 123
    }
  }
}

V2 provides:

• Structured error codes for programmatic handling
• More descriptive error messages
• Additional context in error details
• Consistent error format across all endpoints

Rate limits

Migration checklist

Code examples

Creating a booking

V1:

const response = await fetch(
  'https://api.cal.com/v1/bookings?apiKey=cal_test_xxx',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      eventTypeId: 123,
      start: '2024-01-15T10:00:00Z',
      responses: {
        name: 'John Doe',
        email: '[email protected]'
      }
    })
  }
);

V2:

const response = await fetch(
  'https://api.cal.com/v2/bookings',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer cal_live_xxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      eventTypeId: 123,
      start: '2024-01-15T10:00:00.000Z',
      attendee: {
        name: 'John Doe',
        email: '[email protected]',
        timeZone: 'America/New_York'
      }
    })
  }
);

const data = await response.json();
if (data.status === 'success') {
  console.log('Booking created:', data.data);
}

Fetching event types

V1:

import requests

response = requests.get(
    'https://api.cal.com/v1/event-types',
    params={'apiKey': 'cal_test_xxx'}
)
event_types = response.json()['event_types']

V2:

import requests

response = requests.get(
    'https://api.cal.com/v2/event-types',
    headers={'Authorization': 'Bearer cal_live_xxx'}
)

data = response.json()
if data['status'] == 'success':
    event_types = data['data']

Getting help

If you encounter issues during migration:

1. Check the V2 API Reference for detailed endpoint documentation
2. Review the differences between V1 and V2
3. Contact Cal.com support for migration assistance

Timeline

• Now: V2 is available and recommended for all new integrations
• February 15, 2026: V1 will be discontinued

Start your migration today to ensure a smooth transition and take advantage of V2's enhanced capabilities.