iCalendlyDeveloper Docs
Slots

POSTReserve a slot

Reserves a time slot temporarily.

POST/v2/slots/reservations
POST/v2/slots/reservations

Request Body

application/jsonRequired
eventTypeIdRequirednumber

The ID of the event type for which slot should be reserved.

slotStartRequiredstring

ISO 8601 datestring in UTC timezone representing available slot.

slotDurationnumber

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.

reservationDurationnumber

ONLY for authenticated requests with api key, access token or OAuth credentials (ID + secret).

  For how many minutes the slot should be reserved - for this long time noone else can book this event type at `start` time. If not provided, defaults to 5 minutes.

Header Parameters

cal-api-versionRequiredstring

Must be set to 2024-09-04. If not set to this value, the endpoint will default to an older version.

Default: "2024-09-04"
Authorizationstring

value must be Bearer <token> where <token> is api key prefixed with cal_ or managed user access token

x-cal-client-idstring

For platform customers - OAuth client ID

curl -X POST "https://example.com/v2/slots/reservations" \
  -H "cal-api-version: 2024-09-04" \
  -H "Authorization: <string>" \
  -H "x-cal-client-id: <string>" \
  -H "Content-Type: application/json" \
  -d '{
    "eventTypeId": 1,
    "slotStart": "2024-09-04T09:00:00Z",
    "slotDuration": "30",
    "reservationDuration": 5
  }'

{
  "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"
  }
}

Previous

Get all bookings

Next

Get All Calendars