Slots and Availability API Reference

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

Endpoints Overview

Method	Endpoint	Description
GET	/v2/slots	Get available time slots
POST	/v2/slots/reservations	Reserve a slot temporarily
DELETE	/v2/slots/reservations/{uid}	Release a reserved slot
GET	/v2/calendars/busy-times	Get busy times from calendars

Get Available Slots

Check available time slots for booking an event type.

http

GET /v2/slots

Query Parameters

Parameter	Type	Required	Description
startTime	string	Yes	ISO 8601 start of date range
endTime	string	Yes	ISO 8601 end of date range
eventTypeId	number	Conditional	Event type ID (required if no slug)
eventTypeSlug	string	Conditional	Event type slug (required if no ID)
usernameList	string	Conditional	Comma-separated usernames for team events
timeZone	string	No	Timezone for slot display (default: UTC)
duration	number	No	Override event duration in minutes
rescheduleUid	string	No	Booking UID if rescheduling

Example Request

http

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

Response

json

{
  "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:

json

{
  "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.

http

POST /v2/slots/reservations

Request Body

json

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

Response

json

{
  "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.

http

DELETE /v2/slots/reservations/{uid}

Path Parameters

Parameter	Type	Description
uid	string	Reservation UID

Get Busy Times

Check busy times from connected calendars.

http

GET /v2/calendars/busy-times

Query Parameters

Parameter	Type	Required	Description
startTime	string	Yes	ISO 8601 start of date range
endTime	string	Yes	ISO 8601 end of date range
loggedInUsersTz	string	No	User's timezone
credentialId	number	No	Specific calendar credential ID

Response

json

{
  "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:

http

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

Request Body

json

{
  "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:

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

Best Practices

Efficient Slot Fetching

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

Preventing Double Bookings

Reserve slots: Use slot reservations for multi-step booking flows
Handle expiration: Reservations expire - handle gracefully
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.

http

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.