Slots and Availability API Reference

Detailed documentation for checking availability and managing slots in the Cal.diy API v2.

Endpoints Overview

Get Available Slots

Check available time slots for booking an event type.

GET /v2/slots

Query Parameters

Example Request

GET /v2/slots?startTime=2024-01-15T00:00:00Z&endTime=2024-01-22T00:00:00Z&eventTypeId=123&timeZone=America/New_York

Response

{
  "status": "success",
  "data": {
    "slots": {
      "2024-01-15": [
        {
          "time": "2024-01-15T09:00:00.000Z"
        },
        {
          "time": "2024-01-15T09:30:00.000Z"
        },
        {
          "time": "2024-01-15T10:00:00.000Z"
        }
      ],
      "2024-01-16": [
        {
          "time": "2024-01-16T09:00:00.000Z"
        }
      ]
    }
  }
}

Response with Attendees (Seated Events)

For event types with seatsPerTimeSlot configured:

{
  "status": "success",
  "data": {
    "slots": {
      "2024-01-15": [
        {
          "time": "2024-01-15T09:00:00.000Z",
          "attendees": 3,
          "seatsAvailable": 7
        }
      ]
    }
  }
}

Reserve a Slot

Temporarily reserve a slot while the user completes the booking form. This prevents double-booking.

POST /v2/slots/reservations

Request Body

{
  "eventTypeId": 123,
  "slotUtcStartDate": "2024-01-15T09:00:00.000Z",
  "slotUtcEndDate": "2024-01-15T09:30:00.000Z"
}

Response

{
  "status": "success",
  "data": {
    "uid": "reservation-uid-123",
    "eventTypeId": 123,
    "slotUtcStartDate": "2024-01-15T09:00:00.000Z",
    "slotUtcEndDate": "2024-01-15T09:30:00.000Z",
    "expiresAt": "2024-01-15T08:10:00.000Z"
  }
}

Reservations automatically expire after a short period (typically 10 minutes).

Release a Reserved Slot

Release a slot reservation if the user abandons the booking flow.

DELETE /v2/slots/reservations/{uid}

Path Parameters

Get Busy Times

Check busy times from connected calendars.

GET /v2/calendars/busy-times

Query Parameters

Response

{
  "status": "success",
  "data": [
    {
      "start": "2024-01-15T10:00:00.000Z",
      "end": "2024-01-15T11:00:00.000Z",
      "title": "Existing Meeting",
      "source": "google_calendar"
    }
  ]
}

Routing Form Slots

For routing forms that direct to different event types:

POST /v2/routing-forms/{routingFormId}/calculate-slots

Request Body

{
  "startTime": "2024-01-15T00:00:00Z",
  "endTime": "2024-01-22T00:00:00Z",
  "timeZone": "America/New_York",
  "responses": {
    "field1": "value1",
    "field2": "value2"
  }
}

Understanding Slot Availability

Slots are calculated based on:

1. User's Schedule: Working hours defined in their schedule
2. Existing Bookings: Times already booked
3. Calendar Busy Times: Events from connected calendars
4. Buffer Times: Before/after event buffers
5. Minimum Notice: Minimum booking notice period
6. Booking Limits: Daily/weekly/monthly booking limits

Best Practices

Efficient Slot Fetching

1. Limit date range: Request only the dates you need to display
2. Cache results: Slots don't change frequently, cache for short periods
3. Use timezone parameter: Request slots in user's timezone to avoid conversion

Preventing Double Bookings

1. Reserve slots: Use slot reservations for multi-step booking flows
2. Handle expiration: Reservations expire - handle gracefully
3. Verify before booking: Always verify slot is still available before creating booking

Example Booking Flow

1. User selects date range
   GET /v2/slots?startTime=...&endTime=...&eventTypeId=123

2. User selects a slot
   POST /v2/slots/reservations
   {
     "eventTypeId": 123,
     "slotUtcStartDate": "2024-01-15T09:00:00Z",
     "slotUtcEndDate": "2024-01-15T09:30:00Z"
   }

3. User fills booking form

4. Create booking
   POST /v2/bookings
   {
     "start": "2024-01-15T09:00:00Z",
     "eventTypeId": 123,
     "attendee": {...}
   }

5. If user abandons, release reservation
   DELETE /v2/slots/reservations/{uid}

Timezone Handling

All times in the API are in UTC (ISO 8601 format). Use the timeZone parameter to receive slots in a specific timezone for display purposes.

GET /v2/slots?startTime=2024-01-15T00:00:00Z&endTime=2024-01-22T00:00:00Z&eventTypeId=123&timeZone=Europe/London

The response times will still be in UTC, but the slot calculation will respect the user's timezone for determining available hours.