Reserve a slot
curl --request POST \
--url https://api.cal.com/v2/slots/reservations \
--header 'Content-Type: application/json' \
--header 'cal-api-version: <cal-api-version>' \
--data '
{
"eventTypeId": 1,
"slotStart": "2024-09-04T09:00:00Z",
"slotDuration": 30,
"reservationDuration": 5
}
'import requests
url = "https://api.cal.com/v2/slots/reservations"
payload = {
"eventTypeId": 1,
"slotStart": "2024-09-04T09:00:00Z",
"slotDuration": 30,
"reservationDuration": 5
}
headers = {
"cal-api-version": "<cal-api-version>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'cal-api-version': '<cal-api-version>', 'Content-Type': 'application/json'},
body: JSON.stringify({
eventTypeId: 1,
slotStart: '2024-09-04T09:00:00Z',
slotDuration: 30,
reservationDuration: 5
})
};
fetch('https://api.cal.com/v2/slots/reservations', 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/slots/reservations",
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([
'eventTypeId' => 1,
'slotStart' => '2024-09-04T09:00:00Z',
'slotDuration' => 30,
'reservationDuration' => 5
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"cal-api-version: <cal-api-version>"
],
]);
$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/slots/reservations"
payload := strings.NewReader("{\n \"eventTypeId\": 1,\n \"slotStart\": \"2024-09-04T09:00:00Z\",\n \"slotDuration\": 30,\n \"reservationDuration\": 5\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("cal-api-version", "<cal-api-version>")
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/slots/reservations")
.header("cal-api-version", "<cal-api-version>")
.header("Content-Type", "application/json")
.body("{\n \"eventTypeId\": 1,\n \"slotStart\": \"2024-09-04T09:00:00Z\",\n \"slotDuration\": 30,\n \"reservationDuration\": 5\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cal.com/v2/slots/reservations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cal-api-version"] = '<cal-api-version>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"eventTypeId\": 1,\n \"slotStart\": \"2024-09-04T09:00:00Z\",\n \"slotDuration\": 30,\n \"reservationDuration\": 5\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"data": {
"eventTypeId": 1,
"slotStart": "2024-09-04T09:00:00Z",
"slotEnd": "2024-09-04T10:00:00Z",
"slotDuration": 30,
"reservationUid": "e84be5a3-4696-49e3-acc7-b2f3999c3b94",
"reservationDuration": 5,
"reservationUntil": "2023-09-04T10:00:00Z"
}
}Slots
Reserve a slot
Make a slot not available for others to book for a certain period of time. If you authenticate using oAuth credentials, api key or access token then you can also specify custom duration for how long the slot should be reserved for (defaults to 5 minutes).
Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.
POST
/
v2
/
slots
/
reservations
Reserve a slot
curl --request POST \
--url https://api.cal.com/v2/slots/reservations \
--header 'Content-Type: application/json' \
--header 'cal-api-version: <cal-api-version>' \
--data '
{
"eventTypeId": 1,
"slotStart": "2024-09-04T09:00:00Z",
"slotDuration": 30,
"reservationDuration": 5
}
'import requests
url = "https://api.cal.com/v2/slots/reservations"
payload = {
"eventTypeId": 1,
"slotStart": "2024-09-04T09:00:00Z",
"slotDuration": 30,
"reservationDuration": 5
}
headers = {
"cal-api-version": "<cal-api-version>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'cal-api-version': '<cal-api-version>', 'Content-Type': 'application/json'},
body: JSON.stringify({
eventTypeId: 1,
slotStart: '2024-09-04T09:00:00Z',
slotDuration: 30,
reservationDuration: 5
})
};
fetch('https://api.cal.com/v2/slots/reservations', 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/slots/reservations",
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([
'eventTypeId' => 1,
'slotStart' => '2024-09-04T09:00:00Z',
'slotDuration' => 30,
'reservationDuration' => 5
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"cal-api-version: <cal-api-version>"
],
]);
$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/slots/reservations"
payload := strings.NewReader("{\n \"eventTypeId\": 1,\n \"slotStart\": \"2024-09-04T09:00:00Z\",\n \"slotDuration\": 30,\n \"reservationDuration\": 5\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("cal-api-version", "<cal-api-version>")
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/slots/reservations")
.header("cal-api-version", "<cal-api-version>")
.header("Content-Type", "application/json")
.body("{\n \"eventTypeId\": 1,\n \"slotStart\": \"2024-09-04T09:00:00Z\",\n \"slotDuration\": 30,\n \"reservationDuration\": 5\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cal.com/v2/slots/reservations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cal-api-version"] = '<cal-api-version>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"eventTypeId\": 1,\n \"slotStart\": \"2024-09-04T09:00:00Z\",\n \"slotDuration\": 30,\n \"reservationDuration\": 5\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"data": {
"eventTypeId": 1,
"slotStart": "2024-09-04T09:00:00Z",
"slotEnd": "2024-09-04T10:00:00Z",
"slotDuration": 30,
"reservationUid": "e84be5a3-4696-49e3-acc7-b2f3999c3b94",
"reservationDuration": 5,
"reservationUntil": "2023-09-04T10:00:00Z"
}
}Headers
Body
application/json
By default slot duration is equal to event type length, but if you want to reserve a slot for an event type that has a variable length you can specify it here as a number in minutes. If you don't have this set explicitly that event type can have one of many lengths you can omit this.
Example:
30
Was this page helpful?