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.

ScopeAllows
appointments:readRead appointments, configuration, services and availability
appointments:writeCreate and update appointments
slots:readRead slot availability and schedule tracking records
slots:writeCreate, update and disable calendar windows; update and regenerate tracking

Reading your configuration

GET/v1/appointment-config

Returns 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"
curl -s "https://<your-xebit-voicekit-host>/v1/appointment-config" \
  -H "x-api-key: $XEBIT_API_KEY"

Response, 200 OK:

JSON
{
  "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
    }
  }
}
FieldDescription
timezoneIANA time zone used for every date and time check, for example "Asia/Kolkata".
max_advance_booking_daysHow many days ahead a booking is accepted.
min_notice_hoursMinimum hours of notice needed for a booking.
buffer_time_minutesGap kept between consecutive appointments.
allow_rescheduleWhether rescheduling is allowed.
allow_cancellationWhether cancelling is allowed.
cancellation_notice_hoursMinimum 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

GET/v1/services

Returns 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"
curl -s "https://<your-xebit-voicekit-host>/v1/services" \
  -H "x-api-key: $XEBIT_API_KEY"

Response, 200 OK:

JSON
{
  "success": true,
  "data": [
    { "service_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "General Checkup" },
    { "service_id": "3b8b1c2a-9e4f-4d3a-8c1b-2e5f7a9b0c1d", "name": "Follow-up Visit" }
  ]
}