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:
| Context | Format | Example |
|---|---|---|
| Create, update, disable | Plain calendar_id UUID | "a1b2c3d4-..." |
| Availability response | calendar_id||YYYY-MM-DD | "a1b2c3d4-...||2026-06-15" |
| Schedule tracking response | calendar_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
/v1/appointment-slotsRequires slots:write.
| Name | Type | Required | Description |
|---|---|---|---|
branch_id | string | Yes | Branch UUID the window belongs to. |
day | string | Yes | Day of the week in lower case, for example "monday". |
session | string | Yes | "Morning", "Afternoon" or "Evening". |
ai_slots | integer | Yes | Most appointments the AI voice agent may book in this window. |
max_slots | integer | No | Total capacity of the window. Defaults to ai_slots; must be ≥ ai_slots. |
start_time | string | No | Start time, for example "09:00". |
end_time | string | No | End time, for example "11:00". |
batch_name | string | No | Batch label, for example "MA". Copied onto appointments booked in this window. |
appointment_type_id | string | No | Limit the window to one service (UUID). |
status | string | No | Starting 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"
}'import os
import requests
BASE_URL = "https://api.voice.xebit.ai/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
response = requests.post(
f"{BASE_URL}/appointment-slots",
headers={"x-api-key": API_KEY},
json={
"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"
}
)
print(response.status_code, response.json())const BASE_URL = "https://api.voice.xebit.ai/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const response = await fetch(`${BASE_URL}/appointment-slots`, {
method: "POST",
headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
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"
})
});
console.log(response.status, await response.json());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"
}'import os
import requests
BASE_URL = "https://<your-xebit-voicekit-host>/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
response = requests.post(
f"{BASE_URL}/appointment-slots",
headers={"x-api-key": API_KEY},
json={
"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"
}
)
print(response.status_code, response.json())const BASE_URL = "https://<your-xebit-voicekit-host>/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const response = await fetch(`${BASE_URL}/appointment-slots`, {
method: "POST",
headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
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"
})
});
console.log(response.status, await response.json());Response, 201 Created:
{
"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
/v1/appointment-slots/{slot_id}Requires slots:write. Send only the fields you are changing; at least one is required.
| Field | Description |
|---|---|
day | Day of the week in lower case. |
session | "Morning", "Afternoon" or "Evening". |
start_time | Start time string. |
end_time | End time string. |
max_slots | Total capacity; must be ≥ ai_slots. |
ai_slots | Agent booking limit; must be ≤ max_slots. |
batch_name | Batch 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
}'import os
import requests
BASE_URL = "https://api.voice.xebit.ai/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
slot_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.patch(
f"{BASE_URL}/appointment-slots/{slot_id}",
headers={"x-api-key": API_KEY},
json={
"max_slots": 25,
"ai_slots": 15
}
)
print(response.status_code, response.json())const BASE_URL = "https://api.voice.xebit.ai/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const slotId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(`${BASE_URL}/appointment-slots/${slotId}`, {
method: "PATCH",
headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
max_slots: 25,
ai_slots: 15
})
});
console.log(response.status, await response.json());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
}'import os
import requests
BASE_URL = "https://<your-xebit-voicekit-host>/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
slot_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.patch(
f"{BASE_URL}/appointment-slots/{slot_id}",
headers={"x-api-key": API_KEY},
json={
"max_slots": 25,
"ai_slots": 15
}
)
print(response.status_code, response.json())const BASE_URL = "https://<your-xebit-voicekit-host>/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const slotId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(`${BASE_URL}/appointment-slots/${slotId}`, {
method: "PATCH",
headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
max_slots: 25,
ai_slots: 15
})
});
console.log(response.status, await response.json());Response, 200 OK:
{
"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
/v1/appointment-slots/{slot_id}/disableSets 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"import os
import requests
BASE_URL = "https://api.voice.xebit.ai/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
slot_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.post(
f"{BASE_URL}/appointment-slots/{slot_id}/disable",
headers={"x-api-key": API_KEY}
)
print(response.status_code, response.json())const BASE_URL = "https://api.voice.xebit.ai/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const slotId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(`${BASE_URL}/appointment-slots/${slotId}/disable`, {
method: "POST",
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());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"import os
import requests
BASE_URL = "https://<your-xebit-voicekit-host>/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
slot_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.post(
f"{BASE_URL}/appointment-slots/{slot_id}/disable",
headers={"x-api-key": API_KEY}
)
print(response.status_code, response.json())const BASE_URL = "https://<your-xebit-voicekit-host>/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const slotId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(`${BASE_URL}/appointment-slots/${slotId}/disable`, {
method: "POST",
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());Response, 200 OK:
{
"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
| Status | Code | Cause |
|---|---|---|
400 | VALIDATION_ERROR | A required field is missing, or ai_slots is greater than max_slots. |
404 | NOT_FOUND | No window matches the slot_id. |
403 | INSUFFICIENT_SCOPE | The key lacks the required scope. |