Creating Appointments

Book an appointment into a calendar window with POST /v1/appointments, with idempotent retries and full validation.

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.

POST /v1/appointments books an appointment into one of your calendar windows. Before confirming, the API checks availability, remaining capacity and duplicate rules.

Before you begin

Your key needs the appointments:write scope. In the Xebit VoiceCloud dashboardthe Xebit VoiceKit admin console, make sure you have:

  • at least one service (appointment type);
  • at least one branch with calendar windows for the days and sessions you will book;
  • the right time zone in your organisation configuration (see Appointments Overview).

Create an appointment

POST/v1/appointments

Requires appointments:write.

curl -s -X POST "https://api.voice.xebit.ai/v1/appointments" \
  -H "x-api-key: $XEBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_type": "General Checkup",
    "appointment_date": "2026-06-15T09:30:00.000Z",
    "patient_name": "Aadhi",
    "parent_phone": "+919840XXXXXX",
    "session": "Morning",
    "branch_id": "branch_uuid_here"
  }'
curl -s -X POST "https://<your-xebit-voicekit-host>/v1/appointments" \
  -H "x-api-key: $XEBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_type": "General Checkup",
    "appointment_date": "2026-06-15T09:30:00.000Z",
    "patient_name": "Aadhi",
    "parent_phone": "+919840XXXXXX",
    "session": "Morning",
    "branch_id": "branch_uuid_here"
  }'

Response, 201 Created:

JSON
{
  "success": true,
  "appointment_id": "appt_a1b2c3d4e5",
  "token": null,
  "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"
  }
}

Request fields

NameTypeRequiredDescription
appointment_typestringYesService UUID or readable name, for example "General Checkup". Names are matched without regard to case.
appointment_datestringYesISO 8601 UTC date and time, for example "2026-06-15T09:30:00.000Z". The time part is required.
patient_namestringYesPatient's full name.
parent_phonestringYesPatient's phone number.
branch_idstringConditionalRequired when your organisation has more than one branch; filled in automatically when there is only one. Find IDs with GET /v1/appointment-slots/availability or under Settings → Branches.
sessionstringNo"Morning", "Afternoon" or "Evening". Used to pick the right window.
batchstringNoBatch label, for example "MA". Taken from the matched window when omitted.
assigned_doctorstringNoName or identifier of the assigned doctor.
external_reference_idstringNoYour own unique ID, used for idempotency (below).

About appointment_date. Send a full UTC date and time, not just a date. The engine converts it to your organisation's local time zone (from GET /v1/appointment-config) and checks it against your windows. A date on its own, such as "2026-06-15", becomes UTC midnight and will probably miss every window.

About appointment_type. Pass either the service UUID ("f47ac10b-58cc-4372-a567-0e02b2c3d479") or its name ("General Checkup"). GET /v1/services lists them all.

Idempotency

Send external_reference_id so retries cannot create duplicates. If an active (not cancelled) appointment already exists in your organisation with that reference, the API returns it with "idempotent": true and HTTP 200 instead of 201.

JSON
{
  "success": true,
  "idempotent": true,
  "appointment_id": "appt_a1b2c3d4e5",
  "token": null,
  "data": { ... }
}

Validation rules

  • Future time: appointment_date must be in the future.
  • Slot availability: it must fall inside an active, open window for the branch and session.
  • Capacity: the window must have room left. Each service type is counted separately.
  • No duplicates: one active booking per patient phone number, per appointment type, per date.
  • Valid type: appointment_type must match a configured service.

Error codes

StatusCodeCause
400VALIDATION_ERRORA required field is missing.
400PAST_APPOINTMENTappointment_date is in the past.
409SLOT_FULLThe window has no capacity left.
409SLOT_INACTIVEThe window is closed (status: "CLOSED").
409DUPLICATE_BOOKINGA future, non-cancelled appointment already exists for this phone number. The response includes existing_appointment_id. Applies only when duplicate prevention is switched on in your organisation settings.
422INVALID_APPOINTMENT_TYPEappointment_type matches no configured service.
422OUTSIDE_AVAILABILITYappointment_date is not inside any configured window.
404NOT_FOUNDAppointment not found (GET and PATCH only).
403INSUFFICIENT_SCOPEThe key lacks the required scope.