Schedules

Manage availability schedules through the Cal.com API

The Schedules API allows you to create, retrieve, update, and delete availability schedules that define when users can be booked.

API Version

Schedule endpoints require the cal-api-version header:

cal-api-version: 2024-06-11

Authentication

All schedule endpoints require authentication:

• API Key: Pass via Authorization: Bearer <api-key> header
• Access Token: OAuth access token

Required permissions:

• SCHEDULE_READ for GET operations
• SCHEDULE_WRITE for POST, PATCH, DELETE operations

Overview

Schedules define when a user is available for bookings. Each user should have:

1. Default Schedule: The primary availability schedule used when event types don’t specify a custom schedule
2. Custom Schedules: Additional schedules that specific event types can reference

Create a Schedule

Create a new availability schedule.

cURL - Default Schedule

curl --request POST \
  --url https://api.cal.com/v2/schedules \
  --header 'Authorization: Bearer <api-key>' \
  --header 'cal-api-version: 2024-06-11' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Default Schedule",
    "timeZone": "America/New_York",
    "isDefault": true,
    "availability": [
      {
        "days": [1, 2, 3, 4, 5],
        "startTime": "09:00",
        "endTime": "17:00"
      }
    ]
  }'

Request Body

name · string · required

Schedule name (e.g., “Default Schedule”, “Evening Hours”)

timeZone · string · required

IANA timezone (e.g., “America/New_York”, “Europe/London”)

isDefault · boolean

Whether this is the default schedule. Each user should have exactly one default schedule.

availability · array · required

Array of availability rules

Show child attributes

days · array

Array of day numbers: 0 (Sunday) through 6 (Saturday). Example: [1, 2, 3, 4, 5] for weekdays.

startTime · string

Start time in 24-hour format (e.g., “09:00”, “17:00”)

endTime · string

End time in 24-hour format (e.g., “17:00”, “21:00”)

overrides · array

Date-specific overrides

Show child attributes

date · string

Date in YYYY-MM-DD format

startTime · string

Start time override

endTime · string

End time override

Response

status · string

Status of the response (“success”)

data · object

Schedule details

Show child attributes

id · number

Schedule ID

name · string

Schedule name

timeZone · string

Schedule timezone

isDefault · boolean

Whether this is the default schedule

availability · array

Availability rules

Get Default Schedule

Retrieve the authenticated user’s default schedule.

cURL

curl --request GET \
  --url https://api.cal.com/v2/schedules/default \
  --header 'Authorization: Bearer <api-key>' \
  --header 'cal-api-version: 2024-06-11'

Response

Returns the default schedule object, or null if no default schedule exists.

Get a Schedule

Retrieve a specific schedule by ID.

cURL

curl --request GET \
  --url https://api.cal.com/v2/schedules/{scheduleId} \
  --header 'Authorization: Bearer <api-key>' \
  --header 'cal-api-version: 2024-06-11'

Path Parameters

scheduleId · number · required

The ID of the schedule to retrieve

Get All Schedules

List all schedules for the authenticated user.

cURL

curl --request GET \
  --url https://api.cal.com/v2/schedules \
  --header 'Authorization: Bearer <api-key>' \
  --header 'cal-api-version: 2024-06-11'

Response

{
  "status": "success",
  "data": [
    {
      "id": 123,
      "name": "Default Schedule",
      "timeZone": "America/New_York",
      "isDefault": true,
      "availability": [
        {
          "days": [1, 2, 3, 4, 5],
          "startTime": "09:00",
          "endTime": "17:00"
        }
      ]
    },
    {
      "id": 456,
      "name": "Evening Hours",
      "timeZone": "America/New_York",
      "isDefault": false,
      "availability": [
        {
          "days": [1, 2, 3, 4, 5],
          "startTime": "17:00",
          "endTime": "21:00"
        }
      ]
    }
  ]
}

Update a Schedule

Update an existing schedule.

cURL

curl --request PATCH \
  --url https://api.cal.com/v2/schedules/{scheduleId} \
  --header 'Authorization: Bearer <api-key>' \
  --header 'cal-api-version: 2024-06-11' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Updated Schedule",
    "availability": [
      {
        "days": [1, 2, 3, 4],
        "startTime": "10:00",
        "endTime": "18:00"
      }
    ]
  }'

Path Parameters

scheduleId · number · required

The ID of the schedule to update

Request Body

All fields from the create endpoint are supported. Only include fields you want to update.

Delete a Schedule

Delete a schedule.

cURL

curl --request DELETE \
  --url https://api.cal.com/v2/schedules/{scheduleId} \
  --header 'Authorization: Bearer <api-key>' \
  --header 'cal-api-version: 2024-06-11'

Path Parameters

scheduleId · number · required

The ID of the schedule to delete

Response

{
  "status": "success"
}

Day Numbers

When specifying days in the availability array, use these numbers:

• 0 = Sunday
• 1 = Monday
• 2 = Tuesday
• 3 = Wednesday
• 4 = Thursday
• 5 = Friday
• 6 = Saturday

Time Format

Use 24-hour time format for start and end times:

• Morning: “09:00”, “08:30”
• Afternoon: “13:00”, “14:30”
• Evening: “17:00”, “20:00”

Example Schedules

Standard Business Hours (9-5, Weekdays)

{
  "name": "Business Hours",
  "timeZone": "America/New_York",
  "isDefault": true,
  "availability": [
    {
      "days": [1, 2, 3, 4, 5],
      "startTime": "09:00",
      "endTime": "17:00"
    }
  ]
}

Split Schedule (Morning and Afternoon)

{
  "name": "Split Schedule",
  "timeZone": "Europe/London",
  "isDefault": false,
  "availability": [
    {
      "days": [1, 2, 3, 4, 5],
      "startTime": "09:00",
      "endTime": "12:00"
    },
    {
      "days": [1, 2, 3, 4, 5],
      "startTime": "14:00",
      "endTime": "18:00"
    }
  ]
}

Weekend Availability

{
  "name": "Weekends",
  "timeZone": "America/Los_Angeles",
  "isDefault": false,
  "availability": [
    {
      "days": [0, 6],
      "startTime": "10:00",
      "endTime": "16:00"
    }
  ]
}

Managed Users

For platform customers managing users:

1. Pass timezone when creating managed users to automatically create a default schedule (Monday-Friday, 9AM-5PM)
2. Without a default schedule, users cannot be booked or manage availability
3. Users can modify their schedule via the AvailabilitySettings atom

Linking Schedules to Event Types

After creating a schedule, you can link it to event types:

PATCH /v2/event-types/{eventTypeId}
{
  "scheduleId": 456
}

If no scheduleId is specified, the event type uses the user’s default schedule.

Notes

• Each user must have exactly one default schedule
• Schedules are in the user’s specified timezone
• Event types without a specific scheduleId use the default schedule
• You can create multiple schedules for different availability patterns
• Use overrides for date-specific changes (holidays, time off, etc.)