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
/v1/appointmentsRequires 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"
}'import os
import requests
BASE_URL = "https://api.voice.xebit.ai/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
response = requests.post(
f"{BASE_URL}/appointments",
headers={"x-api-key": API_KEY},
json={
"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"
}
)
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}/appointments`, {
method: "POST",
headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
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"
})
});
console.log(response.status, await response.json());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"
}'import os
import requests
BASE_URL = "https://<your-xebit-voicekit-host>/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
response = requests.post(
f"{BASE_URL}/appointments",
headers={"x-api-key": API_KEY},
json={
"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"
}
)
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}/appointments`, {
method: "POST",
headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
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"
})
});
console.log(response.status, await response.json());Response, 201 Created:
{
"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
| Name | Type | Required | Description |
|---|---|---|---|
appointment_type | string | Yes | Service UUID or readable name, for example "General Checkup". Names are matched without regard to case. |
appointment_date | string | Yes | ISO 8601 UTC date and time, for example "2026-06-15T09:30:00.000Z". The time part is required. |
patient_name | string | Yes | Patient's full name. |
parent_phone | string | Yes | Patient's phone number. |
branch_id | string | Conditional | Required 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. |
session | string | No | "Morning", "Afternoon" or "Evening". Used to pick the right window. |
batch | string | No | Batch label, for example "MA". Taken from the matched window when omitted. |
assigned_doctor | string | No | Name or identifier of the assigned doctor. |
external_reference_id | string | No | Your 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.
{
"success": true,
"idempotent": true,
"appointment_id": "appt_a1b2c3d4e5",
"token": null,
"data": { ... }
}Validation rules
- Future time:
appointment_datemust 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_typemust match a configured service.
Error codes
| Status | Code | Cause |
|---|---|---|
400 | VALIDATION_ERROR | A required field is missing. |
400 | PAST_APPOINTMENT | appointment_date is in the past. |
409 | SLOT_FULL | The window has no capacity left. |
409 | SLOT_INACTIVE | The window is closed (status: "CLOSED"). |
409 | DUPLICATE_BOOKING | A 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. |
422 | INVALID_APPOINTMENT_TYPE | appointment_type matches no configured service. |
422 | OUTSIDE_AVAILABILITY | appointment_date is not inside any configured window. |
404 | NOT_FOUND | Appointment not found (GET and PATCH only). |
403 | INSUFFICIENT_SCOPE | The key lacks the required scope. |