Sign in

v1

latestOpenAPI 3.0.02026-07-17121287546.7 KB
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).

<Note>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.</Note>
post/v2/slots/reservations

Headers

cal-api-versionstring required

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

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

Request body

eventTypeIdnumber required

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

slotStartstring required

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.

Example request

{
  "eventTypeId": 1,
  "slotStart": "2024-09-04T09:00:00Z",
  "reservationDuration": 5
}

Response

status'success' | 'error' required

Example response

{
  "status": "success",
  "data": {
    "eventTypeId": 1,
    "slotStart": "2024-09-04T09:00:00Z",
    "slotEnd": "2024-09-04T10:00:00Z",
    "reservationUid": "e84be5a3-4696-49e3-acc7-b2f3999c3b94",
    "reservationDuration": 5,
    "reservationUntil": "2023-09-04T10:00:00Z"
  }
}