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).

Headers

cal-api-version

string

default:2024-09-04

required

Must be set to 2024-09-04

Authorization

string

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

x-cal-client-id

string

For platform customers - OAuth client ID

Body

application/json

eventTypeId

number

required

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

Example:

1

slotStart

string

required

ISO 8601 datestring in UTC timezone representing available slot.

Example:

"2024-09-04T09:00:00Z"

slotDuration

number

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"

reservationDuration

number

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:

5

Response

201 - application/json

status

enum<string>

required

Available options:

success,

error

Example:

"success"

data

object

required

Show child attributes

data.eventTypeId

number

required

The ID of the event type for which slot was reserved.

Example:

1

data.slotStart

string

required

ISO 8601 datestring in UTC timezone representing available slot.

Example:

"2024-09-04T09:00:00Z"

data.slotEnd

string

required

ISO 8601 datestring in UTC timezone representing slot end.

Example:

"2024-09-04T10:00:00Z"

data.slotDuration

number

required

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. If you don't have this set explicitly that event type can have one of many lengths you can omit this.

Example:

"30"

data.reservationUid

string

required

The unique identifier of the reservation. Use it to update, get or delete the reservation.

Example:

"e84be5a3-4696-49e3-acc7-b2f3999c3b94"

data.reservationDuration

number

required

For how many minutes the slot is reserved - for this long time noone else can book this event type at start time.

Example:

5

data.reservationUntil

string

required

ISO 8601 datestring in UTC timezone representing time until which the slot is reserved.

Example:

"2023-09-04T10:00:00Z"