Appointment Availability

Query live availability and per-date capacity, override a date's tracking record and regenerate tracking after window changes.

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.

These endpoints tell you when appointments can be booked and how full each window is on a given date. They also let you adjust or rebuild the schedule tracking records the booking engine relies on.

Before you begin

  • GET /v1/appointment-slots/availability and GET /v1/appointment-slots/schedule-tracking need the slots:read scope.
  • PATCH /v1/appointment-slots/tracking/:slot_id and POST /v1/appointment-slots/regenerate need the slots:write scope.

Create keys with these scopes in the Xebit VoiceCloud dashboard under Integrations → API Keys.

Create keys with these scopes in the Xebit VoiceKit admin console under Integrations → API Keys.

Get availability

GET/v1/appointment-slots/availability

Lists every open calendar window on one date with live filled and available counts. Requires slots:read.

NameTypeRequiredDescription
datestringYesDate to check, YYYY-MM-DD.
branch_idstringNoOnly this branch (UUID).
sessionstringNoOnly this session: Morning, Afternoon or Evening.
curl -s "https://api.voice.xebit.ai/v1/appointment-slots/availability?date=2026-06-15&session=Morning" \
  -H "x-api-key: $XEBIT_API_KEY"
curl -s "https://<your-xebit-voicekit-host>/v1/appointment-slots/availability?date=2026-06-15&session=Morning" \
  -H "x-api-key: $XEBIT_API_KEY"

Response, 200 OK:

JSON
{
  "success": true,
  "date": "2026-07-15",
  "slots": [
    {
      "slot_id": "f3c2b61b-52d9-4a71-8ae8-63f4464711b9||2026-07-15",
      "calendar_id": "f3c2b61b-52d9-4a71-8ae8-63f4464711b9",
      "parent_calendar_id": null,
      "branch_id": "5dd088a7-285a-405a-a0de-1c6ff0e9bd78",
      "day": "wednesday",
      "session": "evening",
      "batch": "A",
      "start_time": "15:30",
      "end_time": "16:00",
      "appointment_type": null,
      "max_slots": 12,
      "ai_slots": 12,
      "filled_slots": 0,
      "available_slots": 12,
      "status": "OPEN",
      "created_at": "2026-06-19T06:14:13.944Z",
      "updated_at": "2026-07-06T04:43:50.249Z"
    }
  ]
}

Get schedule tracking

GET/v1/appointment-slots/schedule-tracking

Returns the per-date tracking records: the stored fill-count projection the engine keeps for each window and date. Requires slots:read.

NameTypeRequiredDescription
date_fromstringYesStart date, YYYY-MM-DD.
date_tostringNoEnd date, YYYY-MM-DD. Defaults to date_from.
branch_idstringNoOnly this branch (UUID).
appointment_type_idstringNoOnly this service (UUID).
sessionstringNoOnly this session.
curl -s "https://api.voice.xebit.ai/v1/appointment-slots/schedule-tracking?date_from=2026-06-15&date_to=2026-06-21" \
  -H "x-api-key: $XEBIT_API_KEY"
curl -s "https://<your-xebit-voicekit-host>/v1/appointment-slots/schedule-tracking?date_from=2026-06-15&date_to=2026-06-21" \
  -H "x-api-key: $XEBIT_API_KEY"

Response, 200 OK:

JSON
{
  "success": true,
  "data": [
    {
      "slot_id": "f3c2b61b-52d9-4a71-8ae8-63f4464711b9||2026-07-15||",
      "calendar_id": "f3c2b61b-52d9-4a71-8ae8-63f4464711b9",
      "appointment_type_id": null,
      "appointment_type_name": null,
      "date": "2026-07-15",
      "day_of_week": "wednesday",
      "session": "Evening",
      "batch": "A",
      "start_time": "15:30",
      "end_time": "16:00",
      "max_slots": 12,
      "ai_slots": 12,
      "filled_slots": 0,
      "agent_filled": 0,
      "available_slots": 12,
      "status": "OPEN",
      "child_types": [
        "42031a9f-368a-46ee-ba4a-724d744f9c03",
        "13af12ed-4c62-46cb-ae77-88819d3ab4ee",
        "1ef5c539-c545-4c70-a9bd-482cbf62cdf1"
      ]
    }
  ]
}

Update a schedule tracking record

PATCH/v1/appointment-slots/tracking/{slot_id}

Overrides status or max_slots for one date's record. Filled and available counts always come from live appointment data and cannot be set. Requires slots:write.

{slot_id} must be the three part form from a schedule tracking response: calendar_id||YYYY-MM-DD||appointment_type_id.

NameTypeRequiredDescription
statusstringNo"OPEN" or "CLOSED". Overrides the window's status for this date only.
max_slotsintegerNoOverrides the capacity for this date only.
curl -s -X PATCH "https://api.voice.xebit.ai/v1/appointment-slots/tracking/a1b2c3d4-e5f6-7890-abcd-ef1234567890||2026-06-15||f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "x-api-key: $XEBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "CLOSED"
  }'
curl -s -X PATCH "https://<your-xebit-voicekit-host>/v1/appointment-slots/tracking/a1b2c3d4-e5f6-7890-abcd-ef1234567890||2026-06-15||f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "x-api-key: $XEBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "CLOSED"
  }'

Response, 200 OK:

JSON
{
  "success": true,
  "data": {
    "_id": "6a4d45c9f01a52acd5487fea",
    "org_id": "8ba8b0bf-c63e-421c-b22d-1f64a964c155",
    "batch_name": "A",
    "date_str": "2026-07-15",
    "appointment_type_id": null,
    "branch_id": "5dd088a7-285a-405a-a0de-1c6ff0e9bd78",
    "calendar_id": "f3c2b61b-52d9-4a71-8ae8-63f4464711b9",
    "date": "2026-07-14T18:30:00.000Z",
    "day_of_week": "wednesday",
    "session": "Evening",
    "batch_start": "15:30",
    "batch_end": "16:00",
    "max_slots": 12,
    "max_agent_slots": 12,
    "agent_filled": 0,
    "prebooking_filled": 0,
    "walkin_filled": 0,
    "total_filled": 0,
    "available": 12,
    "status": "OPEN",
    "max_slots_overridden": true
  }
}

Regenerate schedule tracking

POST/v1/appointment-slots/regenerate

Rebuilds tracking records for a date range from the current calendar window definitions. Run it after changing windows so the per-date projections match. Requires slots:write.

NameTypeRequiredDescription
date_fromstringYesStart of the range, YYYY-MM-DD.
date_tostringNoEnd of the range, YYYY-MM-DD. Defaults to date_from.
curl -s -X POST "https://api.voice.xebit.ai/v1/appointment-slots/regenerate" \
  -H "x-api-key: $XEBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date_from": "2026-06-15",
    "date_to": "2026-06-30"
  }'
curl -s -X POST "https://<your-xebit-voicekit-host>/v1/appointment-slots/regenerate" \
  -H "x-api-key: $XEBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date_from": "2026-06-15",
    "date_to": "2026-06-30"
  }'

Response, 200 OK:

JSON
{
  "success": true,
  "processed": 16,
  "skipped": 0,
  "errors": 0,
  "upserted": 16
}

Error codes

StatusCodeCause
400VALIDATION_ERRORA required parameter (date or date_from) is missing.
404NOT_FOUNDNo tracking record matches (PATCH only).
403INSUFFICIENT_SCOPEThe key lacks the required scope.