Create a schedule
curl --request POST \
--url https://api.cal.com/v2/organizations/{orgId}/users/{userId}/schedules \
--header 'Content-Type: application/json' \
--data '
{
"name": "Catch up hours",
"timeZone": "Europe/Rome",
"isDefault": true,
"availability": [
{
"days": [
"Monday",
"Tuesday"
],
"startTime": "17:00",
"endTime": "19:00"
},
{
"days": [
"Wednesday",
"Thursday"
],
"startTime": "16:00",
"endTime": "20:00"
}
],
"overrides": [
{
"date": "2024-05-20",
"startTime": "18:00",
"endTime": "21:00"
}
]
}
'import requests
url = "https://api.cal.com/v2/organizations/{orgId}/users/{userId}/schedules"
payload = {
"name": "Catch up hours",
"timeZone": "Europe/Rome",
"isDefault": True,
"availability": [
{
"days": ["Monday", "Tuesday"],
"startTime": "17:00",
"endTime": "19:00"
},
{
"days": ["Wednesday", "Thursday"],
"startTime": "16:00",
"endTime": "20:00"
}
],
"overrides": [
{
"date": "2024-05-20",
"startTime": "18:00",
"endTime": "21:00"
}
]
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Catch up hours',
timeZone: 'Europe/Rome',
isDefault: true,
availability: [
{days: ['Monday', 'Tuesday'], startTime: '17:00', endTime: '19:00'},
{days: ['Wednesday', 'Thursday'], startTime: '16:00', endTime: '20:00'}
],
overrides: [{date: '2024-05-20', startTime: '18:00', endTime: '21:00'}]
})
};
fetch('https://api.cal.com/v2/organizations/{orgId}/users/{userId}/schedules', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cal.com/v2/organizations/{orgId}/users/{userId}/schedules",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Catch up hours',
'timeZone' => 'Europe/Rome',
'isDefault' => true,
'availability' => [
[
'days' => [
'Monday',
'Tuesday'
],
'startTime' => '17:00',
'endTime' => '19:00'
],
[
'days' => [
'Wednesday',
'Thursday'
],
'startTime' => '16:00',
'endTime' => '20:00'
]
],
'overrides' => [
[
'date' => '2024-05-20',
'startTime' => '18:00',
'endTime' => '21:00'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cal.com/v2/organizations/{orgId}/users/{userId}/schedules"
payload := strings.NewReader("{\n \"name\": \"Catch up hours\",\n \"timeZone\": \"Europe/Rome\",\n \"isDefault\": true,\n \"availability\": [\n {\n \"days\": [\n \"Monday\",\n \"Tuesday\"\n ],\n \"startTime\": \"17:00\",\n \"endTime\": \"19:00\"\n },\n {\n \"days\": [\n \"Wednesday\",\n \"Thursday\"\n ],\n \"startTime\": \"16:00\",\n \"endTime\": \"20:00\"\n }\n ],\n \"overrides\": [\n {\n \"date\": \"2024-05-20\",\n \"startTime\": \"18:00\",\n \"endTime\": \"21:00\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cal.com/v2/organizations/{orgId}/users/{userId}/schedules")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Catch up hours\",\n \"timeZone\": \"Europe/Rome\",\n \"isDefault\": true,\n \"availability\": [\n {\n \"days\": [\n \"Monday\",\n \"Tuesday\"\n ],\n \"startTime\": \"17:00\",\n \"endTime\": \"19:00\"\n },\n {\n \"days\": [\n \"Wednesday\",\n \"Thursday\"\n ],\n \"startTime\": \"16:00\",\n \"endTime\": \"20:00\"\n }\n ],\n \"overrides\": [\n {\n \"date\": \"2024-05-20\",\n \"startTime\": \"18:00\",\n \"endTime\": \"21:00\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cal.com/v2/organizations/{orgId}/users/{userId}/schedules")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Catch up hours\",\n \"timeZone\": \"Europe/Rome\",\n \"isDefault\": true,\n \"availability\": [\n {\n \"days\": [\n \"Monday\",\n \"Tuesday\"\n ],\n \"startTime\": \"17:00\",\n \"endTime\": \"19:00\"\n },\n {\n \"days\": [\n \"Wednesday\",\n \"Thursday\"\n ],\n \"startTime\": \"16:00\",\n \"endTime\": \"20:00\"\n }\n ],\n \"overrides\": [\n {\n \"date\": \"2024-05-20\",\n \"startTime\": \"18:00\",\n \"endTime\": \"21:00\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"data": {
"id": 254,
"ownerId": 478,
"name": "Catch up hours",
"timeZone": "Europe/Rome",
"availability": [
{
"days": [
"Monday",
"Tuesday"
],
"startTime": "17:00",
"endTime": "19:00"
},
{
"days": [
"Wednesday",
"Thursday"
],
"startTime": "16:00",
"endTime": "20:00"
}
],
"isDefault": true,
"overrides": [
{
"date": "2024-05-20",
"startTime": "18:00",
"endTime": "21:00"
}
]
}
}Schedules
Create a schedule
Required membership role: org admin. PBAC permission: availability.create. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the ORG_SCHEDULE_WRITE scope is required.
POST
/
v2
/
organizations
/
{orgId}
/
users
/
{userId}
/
schedules
Create a schedule
curl --request POST \
--url https://api.cal.com/v2/organizations/{orgId}/users/{userId}/schedules \
--header 'Content-Type: application/json' \
--data '
{
"name": "Catch up hours",
"timeZone": "Europe/Rome",
"isDefault": true,
"availability": [
{
"days": [
"Monday",
"Tuesday"
],
"startTime": "17:00",
"endTime": "19:00"
},
{
"days": [
"Wednesday",
"Thursday"
],
"startTime": "16:00",
"endTime": "20:00"
}
],
"overrides": [
{
"date": "2024-05-20",
"startTime": "18:00",
"endTime": "21:00"
}
]
}
'import requests
url = "https://api.cal.com/v2/organizations/{orgId}/users/{userId}/schedules"
payload = {
"name": "Catch up hours",
"timeZone": "Europe/Rome",
"isDefault": True,
"availability": [
{
"days": ["Monday", "Tuesday"],
"startTime": "17:00",
"endTime": "19:00"
},
{
"days": ["Wednesday", "Thursday"],
"startTime": "16:00",
"endTime": "20:00"
}
],
"overrides": [
{
"date": "2024-05-20",
"startTime": "18:00",
"endTime": "21:00"
}
]
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Catch up hours',
timeZone: 'Europe/Rome',
isDefault: true,
availability: [
{days: ['Monday', 'Tuesday'], startTime: '17:00', endTime: '19:00'},
{days: ['Wednesday', 'Thursday'], startTime: '16:00', endTime: '20:00'}
],
overrides: [{date: '2024-05-20', startTime: '18:00', endTime: '21:00'}]
})
};
fetch('https://api.cal.com/v2/organizations/{orgId}/users/{userId}/schedules', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cal.com/v2/organizations/{orgId}/users/{userId}/schedules",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Catch up hours',
'timeZone' => 'Europe/Rome',
'isDefault' => true,
'availability' => [
[
'days' => [
'Monday',
'Tuesday'
],
'startTime' => '17:00',
'endTime' => '19:00'
],
[
'days' => [
'Wednesday',
'Thursday'
],
'startTime' => '16:00',
'endTime' => '20:00'
]
],
'overrides' => [
[
'date' => '2024-05-20',
'startTime' => '18:00',
'endTime' => '21:00'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cal.com/v2/organizations/{orgId}/users/{userId}/schedules"
payload := strings.NewReader("{\n \"name\": \"Catch up hours\",\n \"timeZone\": \"Europe/Rome\",\n \"isDefault\": true,\n \"availability\": [\n {\n \"days\": [\n \"Monday\",\n \"Tuesday\"\n ],\n \"startTime\": \"17:00\",\n \"endTime\": \"19:00\"\n },\n {\n \"days\": [\n \"Wednesday\",\n \"Thursday\"\n ],\n \"startTime\": \"16:00\",\n \"endTime\": \"20:00\"\n }\n ],\n \"overrides\": [\n {\n \"date\": \"2024-05-20\",\n \"startTime\": \"18:00\",\n \"endTime\": \"21:00\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cal.com/v2/organizations/{orgId}/users/{userId}/schedules")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Catch up hours\",\n \"timeZone\": \"Europe/Rome\",\n \"isDefault\": true,\n \"availability\": [\n {\n \"days\": [\n \"Monday\",\n \"Tuesday\"\n ],\n \"startTime\": \"17:00\",\n \"endTime\": \"19:00\"\n },\n {\n \"days\": [\n \"Wednesday\",\n \"Thursday\"\n ],\n \"startTime\": \"16:00\",\n \"endTime\": \"20:00\"\n }\n ],\n \"overrides\": [\n {\n \"date\": \"2024-05-20\",\n \"startTime\": \"18:00\",\n \"endTime\": \"21:00\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cal.com/v2/organizations/{orgId}/users/{userId}/schedules")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Catch up hours\",\n \"timeZone\": \"Europe/Rome\",\n \"isDefault\": true,\n \"availability\": [\n {\n \"days\": [\n \"Monday\",\n \"Tuesday\"\n ],\n \"startTime\": \"17:00\",\n \"endTime\": \"19:00\"\n },\n {\n \"days\": [\n \"Wednesday\",\n \"Thursday\"\n ],\n \"startTime\": \"16:00\",\n \"endTime\": \"20:00\"\n }\n ],\n \"overrides\": [\n {\n \"date\": \"2024-05-20\",\n \"startTime\": \"18:00\",\n \"endTime\": \"21:00\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"data": {
"id": 254,
"ownerId": 478,
"name": "Catch up hours",
"timeZone": "Europe/Rome",
"availability": [
{
"days": [
"Monday",
"Tuesday"
],
"startTime": "17:00",
"endTime": "19:00"
},
{
"days": [
"Wednesday",
"Thursday"
],
"startTime": "16:00",
"endTime": "20:00"
}
],
"isDefault": true,
"overrides": [
{
"date": "2024-05-20",
"startTime": "18:00",
"endTime": "21:00"
}
]
}
}Headers
For non-platform customers - value must be Bearer <token> where <token> is api key prefixed with cal_
For platform customers - OAuth client secret key
For platform customers - OAuth client ID
Body
application/json
Example:
"Catch up hours"
Timezone is used to calculate available times when an event using the schedule is booked.
Example:
"Europe/Rome"
Each user should have 1 default schedule. If you specified timeZone when creating managed user, then the default schedule will be created with that timezone.
Default schedule means that if an event type is not tied to a specific schedule then the default schedule is used.
Example:
true
Each object contains days and times when the user is available. If not passed, the default availability is Monday to Friday from 09:00 to 17:00.
Show child attributes
Show child attributes
Example:
[
{
"days": ["Monday", "Tuesday"],
"startTime": "17:00",
"endTime": "19:00"
},
{
"days": ["Wednesday", "Thursday"],
"startTime": "16:00",
"endTime": "20:00"
}
]
Need to change availability for a specific date? Add an override.
Show child attributes
Show child attributes
Example:
[
{
"date": "2024-05-20",
"startTime": "18:00",
"endTime": "21:00"
}
]
Was this page helpful?
⌘I