Getting Appointments

Fetch one appointment by ID or search appointments with filters and pagination.

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.

Fetch a single appointment by its ID, or search your appointments with filters and pages, using the GET /v1/appointments endpoints.

Before you begin

Your key needs the appointments:read scope.

Create it in the Xebit VoiceCloud dashboard under Integrations → API Keys.

Create it in the Xebit VoiceKit admin console under Integrations → API Keys.

Get one appointment

GET/v1/appointments/{appointment_id}

Requires appointments:read.

curl -s "https://api.voice.xebit.ai/v1/appointments/appt_a1b2c3d4e5" \
  -H "x-api-key: $XEBIT_API_KEY"
curl -s "https://<your-xebit-voicekit-host>/v1/appointments/appt_a1b2c3d4e5" \
  -H "x-api-key: $XEBIT_API_KEY"

Response, 200 OK:

JSON
{
  "success": true,
  "data": {
    "appointment_id": "appt_a1b2c3d4e5",
    "appointment_type": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "branch_id": "branch_uuid_here",
    "date": "2026-06-15",
    "session": "Morning",
    "batch": "MA",
    "token": null,
    "patient_name": "Aadhi",
    "parent_phone": "+919840XXXXXX",
    "assigned_doctor": null,
    "status": "confirmed",
    "external_reference_id": null,
    "created_at": "2026-05-26T10:00:00.000Z",
    "updated_at": "2026-05-26T10:00:00.000Z"
  }
}

Returns 404 NOT_FOUND when no appointment with that ID exists in your organisation.

Search appointments

GET/v1/appointments

Requires appointments:read. Every query parameter is optional. Results are ordered by appointment date, earliest first.

NameTypeRequiredDescription
datestringNoDate, YYYY-MM-DD. Matches the whole day in UTC.
statusstringNoconfirmed, rescheduled, cancelled or completed.
appointment_typestringNoService UUID.
branch_idstringNoBranch UUID.
sessionstringNoMorning, Afternoon or Evening.
batchstringNoBatch label, for example "MA".
pageintegerNoPage number. Defaults to 1.
limitintegerNoResults per page. Defaults to 50, maximum 200.
curl -s "https://api.voice.xebit.ai/v1/appointments?date=2026-06-15&session=Morning&page=1&limit=50" \
  -H "x-api-key: $XEBIT_API_KEY"
curl -s "https://<your-xebit-voicekit-host>/v1/appointments?date=2026-06-15&session=Morning&page=1&limit=50" \
  -H "x-api-key: $XEBIT_API_KEY"

Response, 200 OK:

JSON
{
  "success": true,
  "data": [
    {
      "appointment_id": "appt_a1b2c3d4e5",
      "appointment_type": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "branch_id": "branch_uuid_here",
      "date": "2026-06-15",
      "session": "Morning",
      "batch": "MA",
      "token": null,
      "patient_name": "Aadhi",
      "parent_phone": "+919840XXXXXX",
      "assigned_doctor": null,
      "status": "confirmed",
      "external_reference_id": null,
      "created_at": "2026-05-26T10:00:00.000Z",
      "updated_at": "2026-05-26T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 50,
    "total_pages": 1
  }
}

Error codes

StatusCodeCause
404NOT_FOUNDAppointment not found (single fetch only).
403INSUFFICIENT_SCOPEThe key lacks appointments:read.