Appointments Overview
Concepts behind the booking engine (services, branches, calendar windows, schedule tracking), the scopes it needs and how to read its configuration.
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.
Xebit has an appointment booking engine built in. Your CRM, practice management system, website or scripts can read availability and create, change and look up appointments through the same REST API that the voice agents and the dashboard use.
Key concepts
Services (appointment types)
A service is a kind of appointment, such as "General Checkup" or "Follow-up Visit". Each one has a service_id (UUID). When you create an appointment you can pass the UUID or the readable name; names are matched without regard to case. GET /v1/services lists every service in your organisation.
Branches
A branch is a physical location, and every appointment belongs to one. With a single branch, branch_id is filled in for you. With more than one, every create request must include branch_id.
To find a branch_id, call GET /v1/appointment-slots/availability for any future date: each slot in the response names its branch. If no slots exist yet, look under the Xebit VoiceCloud dashboard → Settings → Branchesthe Xebit VoiceKit admin console → Settings → Branches.
Calendar windows
A calendar window is a weekly availability rule, for example "Monday morning, 09:00 to 11:00, up to 20 appointments". It repeats on the same day and session each week, belongs to one branch and can be limited to a single service. Manage windows with the Appointment Slots endpoints.
Schedule tracking
Schedule tracking records project each calendar window onto real dates. The engine creates one record per window per date and keeps its fill counts current as appointments are booked or cancelled. Query them with the Appointment Availability endpoints.
Scopes
Each API key needs the scopes for the calls it makes. Create keys with the right scopes under the Xebit VoiceCloud dashboard → Integrations → API Keys → Generate New Keythe Xebit VoiceKit admin console → Integrations → API Keys → Generate New Key.
| Scope | Allows |
|---|---|
appointments:read | Read appointments, configuration, services and availability |
appointments:write | Create and update appointments |
slots:read | Read slot availability and schedule tracking records |
slots:write | Create, update and disable calendar windows; update and regenerate tracking |
Reading your configuration
/v1/appointment-configReturns your organisation's general booking settings: the time zone, how far ahead people can book and the policy flags. Requires appointments:read.
curl -s "https://api.voice.xebit.ai/v1/appointment-config" \
-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"]
response = requests.get(
f"{BASE_URL}/appointment-config",
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 response = await fetch(`${BASE_URL}/appointment-config`, {
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());curl -s "https://<your-xebit-voicekit-host>/v1/appointment-config" \
-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"]
response = requests.get(
f"{BASE_URL}/appointment-config",
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 response = await fetch(`${BASE_URL}/appointment-config`, {
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());Response, 200 OK:
{
"success": true,
"data": {
"general": {
"enabled": true,
"timezone": "Asia/Kolkata",
"buffer_time_minutes": 15,
"max_advance_booking_days": 30,
"min_notice_hours": 2,
"allow_reschedule": true,
"allow_cancellation": true,
"cancellation_notice_hours": 24
}
}
}| Field | Description |
|---|---|
timezone | IANA time zone used for every date and time check, for example "Asia/Kolkata". |
max_advance_booking_days | How many days ahead a booking is accepted. |
min_notice_hours | Minimum hours of notice needed for a booking. |
buffer_time_minutes | Gap kept between consecutive appointments. |
allow_reschedule | Whether rescheduling is allowed. |
allow_cancellation | Whether cancelling is allowed. |
cancellation_notice_hours | Minimum notice needed to cancel. |
Read timezone before you build any appointment_date. The engine checks times in your organisation's local time zone, so a UTC time that looks fine can land outside every window once converted.
Listing appointment types
/v1/servicesReturns every appointment type in your organisation. Use it to turn names into UUIDs or to fill a type picker. Requires appointments:read.
curl -s "https://api.voice.xebit.ai/v1/services" \
-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"]
response = requests.get(
f"{BASE_URL}/services",
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 response = await fetch(`${BASE_URL}/services`, {
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());curl -s "https://<your-xebit-voicekit-host>/v1/services" \
-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"]
response = requests.get(
f"{BASE_URL}/services",
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 response = await fetch(`${BASE_URL}/services`, {
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());Response, 200 OK:
{
"success": true,
"data": [
{ "service_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "General Checkup" },
{ "service_id": "3b8b1c2a-9e4f-4d3a-8c1b-2e5f7a9b0c1d", "name": "Follow-up Visit" }
]
}