Bookings API Reference

Detailed documentation for booking-related endpoints in the Cal.diy API v2.

Endpoints Overview

List Bookings

GET /v2/bookings

Query Parameters

Response

{
  "status": "success",
  "data": [
    {
      "id": 12345,
      "uid": "abc123def456",
      "title": "30 Minute Meeting",
      "description": "Discussion about project",
      "start": "2024-01-15T10:00:00.000Z",
      "end": "2024-01-15T10:30:00.000Z",
      "status": "accepted",
      "eventTypeId": 123,
      "attendees": [
        {
          "name": "John Doe",
          "email": "john@example.com",
          "timeZone": "America/New_York"
        }
      ],
      "hosts": [
        {
          "id": 456,
          "name": "Jane Smith",
          "email": "jane@company.com"
        }
      ],
      "location": "https://cal.com/video/abc123",
      "meetingUrl": "https://cal.com/video/abc123",
      "metadata": {},
      "createdAt": "2024-01-10T08:00:00.000Z"
    }
  ]
}

Create a Booking

POST /v2/bookings

Request Body

{
  "start": "2024-01-15T10:00:00Z",
  "eventTypeId": 123,
  "attendee": {
    "name": "John Doe",
    "email": "john@example.com",
    "timeZone": "America/New_York",
    "language": "en"
  },
  "guests": ["guest1@example.com", "guest2@example.com"],
  "meetingUrl": "https://cal.com/team/meeting",
  "metadata": {
    "customField": "value"
  },
  "bookingFieldsResponses": {
    "notes": "Please prepare the quarterly report"
  }
}

Required Fields

Optional Fields

Response

{
  "status": "success",
  "data": {
    "id": 12345,
    "uid": "abc123def456",
    "title": "30 Minute Meeting",
    "start": "2024-01-15T10:00:00.000Z",
    "end": "2024-01-15T10:30:00.000Z",
    "status": "accepted",
    "eventTypeId": 123,
    "attendees": [...],
    "hosts": [...],
    "location": "https://cal.com/video/abc123"
  }
}

Get a Booking

GET /v2/bookings/{bookingUid}

Path Parameters

Response

Returns the full booking object with all details.

Cancel a Booking

POST /v2/bookings/{bookingUid}/cancel

Request Body

{
  "cancellationReason": "Schedule conflict"
}

Fields

Reschedule a Booking

POST /v2/bookings/{bookingUid}/reschedule

Request Body

{
  "start": "2024-01-16T14:00:00Z",
  "reschedulingReason": "Conflict with another meeting"
}

Fields

Confirm a Booking

For event types that require confirmation:

POST /v2/bookings/{bookingUid}/confirm

Decline a Booking

POST /v2/bookings/{bookingUid}/decline

Request Body

{
  "reason": "Not available at this time"
}

Update Booking Location

PATCH /v2/bookings/{bookingUid}/location

Request Body

{
  "location": "https://zoom.us/j/123456789"
}

Mark Attendee as No-Show

POST /v2/bookings/{bookingUid}/mark-absent

Request Body

{
  "attendeeEmail": "john@example.com",
  "noShow": true
}

Reassign Booking

Reassign a booking to a different host:

POST /v2/bookings/{bookingUid}/reassign

Or to a specific user:

POST /v2/bookings/{bookingUid}/reassign/{userId}

Get Booking References

Get external references (calendar events, video meetings) for a booking:

GET /v2/bookings/{bookingUid}/references

Response

{
  "status": "success",
  "data": [
    {
      "type": "google_calendar",
      "uid": "calendar-event-id",
      "meetingUrl": "https://meet.google.com/abc-defg-hij"
    }
  ]
}

Booking Statuses

Common Use Cases

Book a Meeting

1. Get available slots: GET /v2/slots?eventTypeId=123&startTime=...&endTime=...
2. Create booking: POST /v2/bookings with selected slot
3. Store the booking UID for future operations

Reschedule Flow

1. Get new available slots: GET /v2/slots?eventTypeId=123&startTime=...&endTime=...
2. Reschedule: POST /v2/bookings/{uid}/reschedule with new start time

Cancel with Notification

1. Cancel: POST /v2/bookings/{uid}/cancel with reason
2. Attendees automatically receive cancellation emails