Migrating from API v1 to v2

Why migrate to v2?

The v2 API includes numerous enhancements and new features that are not available in v1:

• Performance improvements: Optimized for better performance and scalability
• User-friendly response objects: Improved response structure for better developer experience
• Enhanced security: Improved security measures to protect your data
• New features: Access to new Cal.com features only available in v2
• Better error handling: More descriptive error messages and status codes

Authentication changes

In v1, you authenticated using an API key passed as a query parameter:

curl https://api.cal.com/v1/bookings?apiKey=cal_test_xxxxxx

In v2, you authenticate using an API key in the Authorization header:

curl https://api.cal.com/v2/bookings \
  -H "Authorization: Bearer cal_test_xxxxxx" \
  -H "cal-api-version: 2024-08-13"

Endpoint-by-endpoint migration guide

Bookings

Create a booking

V1 endpoint:

POST /v1/bookings

V1 request body:

{
  "eventTypeId": 123,
  "start": "2023-05-24T13:00:00.000Z",
  "end": "2023-05-24T13:30:00.000Z",
  "responses": {
    "name": "John Doe",
    "email": "[email protected]",
    "location": {
      "value": "userPhone",
      "optionValue": ""
    }
  },
  "timeZone": "Europe/London",
  "language": "en",
  "metadata": {}
}

V2 endpoint:

POST /v2/bookings

V2 request body:

{
  "eventTypeId": 123,
  "start": "2024-08-13T09:00:00Z",
  "attendee": {
    "name": "John Doe",
    "email": "[email protected]",
    "timeZone": "America/New_York",
    "language": "en"
  },
  "location": {
    "type": "phone"
  },
  "metadata": {}
}

Key differences:

• responses object replaced with attendee object
• end time is no longer required (calculated from event type duration)
• location structure changed from {value, optionValue} to {type}
• Must include cal-api-version: 2024-08-13 header
• Response structure is more detailed with status and data wrapper

V1 response:

{
  "booking": {
    "id": 91,
    "uid": "bFJeNb2uX8ANpT3JL5EfXw",
    "startTime": "2023-05-25T09:30:00.000Z",
    "endTime": "2023-05-25T10:30:00.000Z",
    "attendees": [...],
    "status": "ACCEPTED"
  }
}

V2 response:

{
  "status": "success",
  "data": {
    "id": 123,
    "uid": "booking_uid_123",
    "start": "2024-08-13T15:30:00Z",
    "end": "2024-08-13T16:30:00Z",
    "duration": 60,
    "status": "accepted",
    "hosts": [...],
    "attendees": [...],
    "eventType": {
      "id": 1,
      "slug": "some-event"
    }
  }
}

Get all bookings

V1: Not available as a dedicated endpoint

V2 endpoint:

GET /v2/bookings

V2 query parameters:

• status: Filter by booking status (accepted, pending, cancelled, rejected)
• attendeeEmail: Filter by attendee email
• eventTypeId: Filter by event type
• afterStart, beforeEnd: Filter by date range
• take, skip: Pagination
• sortStart, sortEnd, sortCreated: Sorting options

V2 response includes pagination:

{
  "status": "success",
  "data": [...],
  "pagination": {
    "totalItems": 123,
    "currentPage": 2,
    "totalPages": 13,
    "hasNextPage": true
  }
}

Cancel a booking

V1 endpoint:

DELETE /v1/bookings?id={id}&allRemainingBookings=false&cancellationReason=reason

V2 endpoint:

POST /v2/bookings/{uid}/cancel

V2 request body:

{
  "cancellationReason": "User requested cancellation"
}

Key differences:

• Changed from DELETE to POST method
• Uses booking uid in path instead of id query parameter
• Cancellation reason in request body instead of query parameter

Reschedule a booking

V1: Required creating a new booking with rescheduleUid

V2 endpoint:

POST /v2/bookings/{uid}/reschedule

V2 request body:

{
  "start": "2024-08-14T10:00:00Z",
  "reschedulingReason": "Conflict with another meeting"
}

Key differences:

• Dedicated reschedule endpoint in v2
• Simpler process - just provide new start time
• Automatically handles the relationship between old and new bookings

Event types

Get all event types

V1 endpoint:

GET /v1/event-types

V2 endpoint:

GET /v2/event-types

Key differences:

• V2 response includes more detailed information about each event type
• V2 includes pagination support
• V2 response wrapped in {status, data} structure

Create an event type

V1 endpoint:

POST /v1/event-types

V1 request body:

{
  "title": "30 Min Meeting",
  "slug": "30min",
  "length": 30,
  "locations": [{"type": "integrations:zoom"}]
}

V2 endpoint:

POST /v2/event-types

V2 request body:

{
  "title": "30 Min Meeting",
  "slug": "30min",
  "lengthInMinutes": 30,
  "locations": [{"type": "zoom"}]
}

Key differences:

• length renamed to lengthInMinutes for clarity
• Location types simplified (no integrations: prefix)
• More configuration options available in v2

Update an event type

V1 endpoint:

PATCH /v1/event-types/{id}

V2 endpoint:

PATCH /v2/event-types/{id}

Key differences:

• Same HTTP method and path structure
• Request/response body structure differences match create endpoint
• V2 provides more granular control over event type settings

Schedules

Get all schedules

V1 endpoint:

GET /v1/schedules

V2 endpoint:

GET /v2/schedules

Key differences:

• V2 includes default schedule indicator
• V2 response includes more detailed availability information
• V2 supports filtering and pagination

Create a schedule

V1 endpoint:

POST /v1/schedules

V1 request body:

{
  "name": "Working Hours",
  "timeZone": "America/New_York",
  "availability": [...]
}

V2 endpoint:

POST /v2/schedules

V2 request body:

{
  "name": "Working Hours",
  "timeZone": "America/New_York",
  "isDefault": false,
  "schedule": [...]
}

Key differences:

• availability renamed to schedule in v2
• isDefault flag added to set default schedule
• More flexible schedule configuration options

Webhooks

Get all webhooks

V1 endpoint:

GET /v1/webhooks

V2 endpoint:

GET /v2/webhooks

Create a webhook

V1 endpoint:

POST /v1/webhooks

V1 request body:

{
  "subscriberUrl": "https://example.com/webhook",
  "eventTriggers": ["BOOKING_CREATED"],
  "active": true
}

V2 endpoint:

POST /v2/webhooks

V2 request body:

{
  "payloadTemplate": null,
  "triggers": ["BOOKING_CREATED"],
  "subscriberUrl": "https://example.com/webhook",
  "active": true
}

Key differences:

• eventTriggers renamed to triggers
• Added payloadTemplate for custom webhook payloads
• More webhook event types available in v2

Slots

Get available slots

V1 endpoint:

GET /v1/slots/available?eventTypeId=123&startTime=2024-01-01&endTime=2024-01-31

V2 endpoint:

GET /v2/slots/available?eventTypeId=123&startTime=2024-01-01T00:00:00Z&endTime=2024-01-31T23:59:59Z

Key differences:

• V2 requires full ISO 8601 timestamps
• V2 response includes more metadata about slot availability
• V2 supports additional filtering options (username, teamSlug, etc.)

Teams

Get all teams

V1 endpoint:

GET /v1/teams

V2 endpoint:

GET /v2/teams

Key differences:

• V2 includes organization context if team is part of an org
• V2 response includes more team metadata
• V2 supports pagination

Users

Get user profile

V1 endpoint:

GET /v1/users/{id}

V2 endpoint:

GET /v2/me

Key differences:

• V2 uses /me endpoint for current user
• V2 returns more detailed profile information
• V2 includes organization and team memberships

Response structure changes

V1 response format

{
  "booking": {...}
}

V2 response format

{
  "status": "success",
  "data": {...}
}

All v2 responses follow this consistent structure with:

• status: Either "success" or "error"
• data: The actual response data
• error: Error details (only present when status is "error")

Error handling

V1 errors

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

V2 errors

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

V2 provides more structured error responses with error codes for better error handling.

Migration checklist

• Update authentication to use Authorization header instead of query parameter
• Add cal-api-version: 2024-08-13 header to all requests
• Update base URL from /v1/ to /v2/
• Update request body structures (especially responses → attendee for bookings)
• Update response parsing to handle {status, data} wrapper
• Update location object structures
• Update field names (length → lengthInMinutes, eventTriggers → triggers, etc.)
• Implement pagination handling for list endpoints
• Update error handling to parse new error structure
• Test all endpoints in your integration
• Update any stored booking/event type IDs if needed

Need help?

If you have questions or need assistance with migrating to v2, please contact our support team.