Appointment Slots

Create, update and disable calendar windows, the weekly rules that set when and how many appointments can be booked.

Showing instructions for Xebit VoiceCloud.Showing instructions for Xebit VoiceKit, on your own infrastructure. Switch with the selector at the top. Updated 22 October 2026.

Calendar windows are the weekly rules that decide when appointments can be booked and how many. Each window belongs to a branch and repeats on a fixed day and session. To see what is open and how full it is on particular dates, use GET /v1/appointment-slots/availability and GET /v1/appointment-slots/schedule-tracking on Appointment Availability.

Before you begin

Creating, updating and disabling windows needs the slots:write scope on your key.

Issue the key from the Xebit VoiceCloud dashboard.

Issue the key from the Xebit VoiceKit admin console of your deployment.

slot_id format

slot_id takes different shapes depending on where it comes from:

ContextFormatExample
Create, update, disablePlain calendar_id UUID"a1b2c3d4-..."
Availability responsecalendar_id||YYYY-MM-DD"a1b2c3d4-...||2026-06-15"
Schedule tracking responsecalendar_id||YYYY-MM-DD||appointment_type_id"a1b2c3d4-...||2026-06-15||f47ac10b-..."

For the PATCH and disable endpoints the server uses only the first segment, so you can pass the plain UUID or a compound value straight from an availability response.

Create a calendar window

POST/v1/appointment-slots

Requires slots:write.

NameTypeRequiredDescription
branch_idstringYesBranch UUID the window belongs to.
daystringYesDay of the week in lower case, for example "monday".
sessionstringYes"Morning", "Afternoon" or "Evening".
ai_slotsintegerYesMost appointments the AI voice agent may book in this window.
max_slotsintegerNoTotal capacity of the window. Defaults to ai_slots; must be ≥ ai_slots.
start_timestringNoStart time, for example "09:00".
end_timestringNoEnd time, for example "11:00".
batch_namestringNoBatch label, for example "MA". Copied onto appointments booked in this window.
appointment_type_idstringNoLimit the window to one service (UUID).
statusstringNoStarting status: "OPEN" (default) or "CLOSED".
curl -s -X POST "https://api.voice.xebit.ai/v1/appointment-slots" \
  -H "x-api-key: $XEBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "branch_id": "branch_uuid_here",
    "day": "monday",
    "session": "Morning",
    "start_time": "09:00",
    "end_time": "11:00",
    "max_slots": 20,
    "ai_slots": 10,
    "batch_name": "MA",
    "appointment_type_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }'
curl -s -X POST "https://<your-xebit-voicekit-host>/v1/appointment-slots" \
  -H "x-api-key: $XEBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "branch_id": "branch_uuid_here",
    "day": "monday",
    "session": "Morning",
    "start_time": "09:00",
    "end_time": "11:00",
    "max_slots": 20,
    "ai_slots": 10,
    "batch_name": "MA",
    "appointment_type_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }'

Response, 201 Created:

JSON
{
  "success": true,
  "data": {
    "slot_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "calendar_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "parent_calendar_id": null,
    "branch_id": "branch_uuid_here",
    "day": "monday",
    "session": "Morning",
    "batch": "MA",
    "start_time": "09:00",
    "end_time": "11:00",
    "appointment_type": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "max_slots": 20,
    "ai_slots": 10,
    "filled_slots": null,
    "available_slots": null,
    "status": "OPEN",
    "created_at": "2026-05-26T10:00:00.000Z",
    "updated_at": "2026-05-26T10:00:00.000Z"
  }
}

ai_slots and max_slots. ai_slots caps what the voice agent can fill; max_slots is the window's total capacity. If your staff can see 20 people but you want the agent to book only 10, set max_slots: 20 and ai_slots: 10.

Update a calendar window

PATCH/v1/appointment-slots/{slot_id}

Requires slots:write. Send only the fields you are changing; at least one is required.

FieldDescription
dayDay of the week in lower case.
session"Morning", "Afternoon" or "Evening".
start_timeStart time string.
end_timeEnd time string.
max_slotsTotal capacity; must be ≥ ai_slots.
ai_slotsAgent booking limit; must be ≤ max_slots.
batch_nameBatch label.
status"OPEN" or "CLOSED".
curl -s -X PATCH "https://api.voice.xebit.ai/v1/appointment-slots/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-api-key: $XEBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "max_slots": 25,
    "ai_slots": 15
  }'
curl -s -X PATCH "https://<your-xebit-voicekit-host>/v1/appointment-slots/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-api-key: $XEBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "max_slots": 25,
    "ai_slots": 15
  }'

Response, 200 OK:

JSON
{
  "success": true,
  "data": {
    "slot_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "calendar_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "parent_calendar_id": null,
    "branch_id": "branch_uuid_here",
    "day": "monday",
    "session": "Morning",
    "batch": "MA",
    "start_time": "09:00",
    "end_time": "11:00",
    "appointment_type": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "max_slots": 25,
    "ai_slots": 15,
    "filled_slots": null,
    "available_slots": null,
    "status": "OPEN",
    "created_at": "2026-05-26T10:00:00.000Z",
    "updated_at": "2026-05-26T11:00:00.000Z"
  }
}

Disable a calendar window

POST/v1/appointment-slots/{slot_id}/disable

Sets the window to CLOSED so nothing new can be booked into it. Windows cannot be deleted; disabling is how you take one offline. Requires slots:write.

curl -s -X POST "https://api.voice.xebit.ai/v1/appointment-slots/a1b2c3d4-e5f6-7890-abcd-ef1234567890/disable" \
  -H "x-api-key: $XEBIT_API_KEY"
curl -s -X POST "https://<your-xebit-voicekit-host>/v1/appointment-slots/a1b2c3d4-e5f6-7890-abcd-ef1234567890/disable" \
  -H "x-api-key: $XEBIT_API_KEY"

Response, 200 OK:

JSON
{
  "success": true,
  "data": {
    "slot_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "calendar_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "parent_calendar_id": null,
    "branch_id": "branch_uuid_here",
    "day": "monday",
    "session": "Morning",
    "batch": "MA",
    "start_time": "09:00",
    "end_time": "11:00",
    "appointment_type": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "max_slots": 20,
    "ai_slots": 10,
    "filled_slots": null,
    "available_slots": null,
    "status": "CLOSED",
    "created_at": "2026-05-26T10:00:00.000Z",
    "updated_at": "2026-05-26T12:00:00.000Z"
  }
}

To bring a disabled window back, send PATCH /v1/appointment-slots/{slot_id} with { "status": "OPEN" }.

Error codes

StatusCodeCause
400VALIDATION_ERRORA required field is missing, or ai_slots is greater than max_slots.
404NOT_FOUNDNo window matches the slot_id.
403INSUFFICIENT_SCOPEThe key lacks the required scope.