Availability

Check available time slots for bookings

The Availability API allows you to retrieve available time slots for event types and users.

API Version

Availability endpoints require the cal-api-version header:

cal-api-version: 2024-09-04

Authentication

Availability endpoints support optional authentication:

• API Key: Pass via Authorization: Bearer <api-key> header (optional)
• Access Token: OAuth access token (optional)
• Client Credentials: Use x-cal-client-id header (optional)

Get Available Slots

Retrieve available time slots for an event type.

cURL - By Event Type ID

curl --request GET \
  --url 'https://api.cal.com/v2/slots?eventTypeId=123&start=2024-12-05&end=2024-12-12&timeZone=America/New_York' \
  --header 'cal-api-version: 2024-09-04'

Query Parameters

Required Parameters

start · string · required

Start date in YYYY-MM-DD format (e.g., “2024-12-05”)

end · string · required

End date in YYYY-MM-DD format (e.g., “2024-12-12”)

Event Type Identification

Choose one of the following methods to identify the event type:

Method 1: By Event Type ID

eventTypeId · number

The ID of the event type

Method 2: By Event Type Slug + Username

eventTypeSlug · string

The slug of the event type

username · string

Username of the event type owner

organizationSlug · string

Organization slug (if user is in an organization)

Method 3: By Event Type Slug + Team Slug

eventTypeSlug · string

The slug of the team event type

teamSlug · string

The team’s slug

organizationSlug · string

Organization slug (if team is in an organization)

Method 4: Dynamic Event (Multiple Users)

usernames · string

Comma-separated list of usernames (minimum 2). Used to find when multiple people are available.

organizationSlug · string

Organization slug (required for dynamic events)

Optional Parameters

timeZone · string

Timezone for the slots (e.g., “America/New_York”). Defaults to UTC.

duration · number

Duration in minutes. Required for:

• Event types with multiple duration options
• Dynamic events (defaults to 30)

format · string

Response format:

• "time" (default): Returns start times only
• "range": Returns start and end times

bookingUidToReschedule · string

When rescheduling, provide the booking UID to exclude its time from busy calculations

Response Format

Default Format (time)

{
  "status": "success",
  "data": {
    "2024-12-05": ["09:00", "09:30", "10:00", "10:30"],
    "2024-12-06": ["09:00", "09:30", "10:00"],
    "2024-12-07": []
  }
}

Range Format

{
  "status": "success",
  "data": {
    "2024-12-05": [
      { "start": "09:00", "end": "09:30" },
      { "start": "09:30", "end": "10:00" },
      { "start": "10:00", "end": "10:30" }
    ],
    "2024-12-06": [
      { "start": "09:00", "end": "09:30" }
    ]
  }
}

Use Cases

Individual User Event Types

There are 4 ways to get slots for individual user event types:

1. By Event Type ID

   /v2/slots?eventTypeId=123&start=2024-12-05&end=2024-12-06&timeZone=America/New_York
   

2. By Slug and Username

   /v2/slots?eventTypeSlug=30-min&username=alice&start=2024-12-05&end=2024-12-06
   

3. Within an Organization

   /v2/slots?organizationSlug=acme&eventTypeSlug=30-min&username=alice&start=2024-12-05&end=2024-12-06
   

4. Dynamic Event (Multiple Users)

   /v2/slots?usernames=alice,bob&organizationSlug=acme&start=2024-12-05&end=2024-12-06
   

Team Event Types

There are 3 ways to get slots for team event types:

1. By Event Type ID

   /v2/slots?eventTypeId=456&start=2024-12-05&end=2024-12-06
   

2. By Slug and Team Slug

   /v2/slots?eventTypeSlug=team-meeting&teamSlug=engineering&start=2024-12-05&end=2024-12-06
   

3. Within an Organization

   /v2/slots?organizationSlug=acme&eventTypeSlug=team-meeting&teamSlug=engineering&start=2024-12-05&end=2024-12-06
   

Rescheduling

When rescheduling a booking, pass the booking UID to exclude its time from busy calculations:

curl --request GET \
  --url 'https://api.cal.com/v2/slots?eventTypeId=123&start=2024-12-05&end=2024-12-06&bookingUidToReschedule=abc-123-def' \
  --header 'cal-api-version: 2024-09-04'

Reserve a Slot

Reserve a specific time slot temporarily (holds the slot for a short period).

POST /v2/slots/reserve

Request Body

{
  "eventTypeId": 123,
  "slotUtcStartDate": "2024-12-05T14:00:00Z",
  "slotUtcEndDate": "2024-12-05T14:30:00Z"
}

Important Notes

Managed Event Types

Managed event types are templates that create individual child event types for each team member. You cannot fetch slots for the parent managed event type directly. Instead:

1. Find the child event type IDs (assigned to specific users)
2. Use those child event type IDs to fetch slots as individual user event types

Time Zones

• All times in the response are in the specified timeZone parameter
• If no timezone is provided, times are returned in UTC
• Use IANA timezone format (e.g., “America/New_York”, “Europe/London”)

Performance

• Keep the date range reasonable (1-4 weeks recommended)
• Larger date ranges will take longer to compute
• Consider caching results for frequently accessed event types