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 operationsSCHEDULE_WRITE for POST, PATCH, DELETE operations
Overview
Schedules define when a user is available for bookings. Each user should have:
- Default Schedule: The primary availability schedule used when event types don’t specify a custom schedule
- Custom Schedules: Additional schedules that specific event types can reference
Create a Schedule
Create a new availability 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
Schedule name (e.g., “Default Schedule”, “Evening Hours”)
IANA timezone (e.g., “America/New_York”, “Europe/London”)
Whether this is the default schedule. Each user should have exactly one default schedule.
Array of availability rules
Array of day numbers: 0 (Sunday) through 6 (Saturday). Example: [1, 2, 3, 4, 5] for weekdays.
Start time in 24-hour format (e.g., “09:00”, “17:00”)
End time in 24-hour format (e.g., “17:00”, “21:00”)
Date-specific overrides
Date in YYYY-MM-DD format
Response
Status of the response (“success”)
Schedule details
Whether this is the default schedule
Get Default Schedule
Retrieve the authenticated user’s default schedule.
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 --request GET \
--url https://api.cal.com/v2/schedules/{scheduleId} \
--header 'Authorization: Bearer <api-key>' \
--header 'cal-api-version: 2024-06-11'
Path Parameters
The ID of the schedule to retrieve
Get All Schedules
List all schedules for the authenticated user.
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 --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
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 --request DELETE \
--url https://api.cal.com/v2/schedules/{scheduleId} \
--header 'Authorization: Bearer <api-key>' \
--header 'cal-api-version: 2024-06-11'
Path Parameters
The ID of the schedule to delete
Response
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
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:
- Pass timezone when creating managed users to automatically create a default schedule (Monday-Friday, 9AM-5PM)
- Without a default schedule, users cannot be booked or manage availability
- 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
}
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.)
