Cancelling Appointments
Cancel an appointment by setting its status to cancelled with PATCH /v1/appointments/{appointment_id}.
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.
To cancel an appointment, set its status to cancelled with PATCH /v1/appointments/{appointment_id}. There is no separate cancel endpoint; cancelling is a status change, so you can update other fields in the same request.
Before you begin
Your key needs the appointments:write scope. Whether cancelling is allowed at all depends on the allow_cancellation and cancellation_notice_hours settings in your organisation configuration (see Appointments Overview).
Those settings are managed in the Xebit VoiceCloud dashboard.
Those settings are managed in the Xebit VoiceKit admin console of your deployment.
Cancel an appointment
/v1/appointments/{appointment_id}Requires appointments:write.
curl -s -X PATCH "https://api.voice.xebit.ai/v1/appointments/appt_a1b2c3d4e5" \
-H "x-api-key: $XEBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "cancelled"
}'import os
import requests
BASE_URL = "https://api.voice.xebit.ai/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
appointment_id = "appt_a1b2c3d4e5"
response = requests.patch(
f"{BASE_URL}/appointments/{appointment_id}",
headers={"x-api-key": API_KEY},
json={
"status": "cancelled"
}
)
print(response.status_code, response.json())const BASE_URL = "https://api.voice.xebit.ai/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const appointmentId = "appt_a1b2c3d4e5";
const response = await fetch(`${BASE_URL}/appointments/${appointmentId}`, {
method: "PATCH",
headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
status: "cancelled"
})
});
console.log(response.status, await response.json());curl -s -X PATCH "https://<your-xebit-voicekit-host>/v1/appointments/appt_a1b2c3d4e5" \
-H "x-api-key: $XEBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "cancelled"
}'import os
import requests
BASE_URL = "https://<your-xebit-voicekit-host>/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
appointment_id = "appt_a1b2c3d4e5"
response = requests.patch(
f"{BASE_URL}/appointments/{appointment_id}",
headers={"x-api-key": API_KEY},
json={
"status": "cancelled"
}
)
print(response.status_code, response.json())const BASE_URL = "https://<your-xebit-voicekit-host>/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const appointmentId = "appt_a1b2c3d4e5";
const response = await fetch(`${BASE_URL}/appointments/${appointmentId}`, {
method: "PATCH",
headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
status: "cancelled"
})
});
console.log(response.status, await response.json());Response, 200 OK:
{
"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": "cancelled",
"external_reference_id": null,
"created_at": "2026-05-26T10:00:00.000Z",
"updated_at": "2026-05-26T12:00:00.000Z"
}
}Important constraints
Cancellation policy. Your organisation settings govern cancelling. Check them with GET /v1/appointment-config:
allow_cancellation: whenfalse, the API rejects cancellation requests.cancellation_notice_hours: the minimum notice, in hours before the appointment, needed to cancel.
- Idempotency: cancelling an appointment that is already cancelled is safe; the API returns the current record without an error.
- No deletion: appointments are never deleted. A cancelled appointment still appears in search results and can be fetched by ID.
- Capacity is released: cancelling decrements the slot's filled count, so the place can be booked again.
Error codes
| Status | Code | Cause |
|---|---|---|
404 | NOT_FOUND | Appointment not found. |
403 | INSUFFICIENT_SCOPE | The key lacks the required scope. |