Updating Appointments
Reschedule an appointment, assign a doctor, add notes or change its status 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.
Change an existing appointment with PATCH /v1/appointments/{appointment_id}: move it to a new time, assign a doctor, add notes or set a new status.
Before you begin
Your key needs the appointments:write scope.
Create it in the Xebit VoiceCloud dashboard under Integrations → API Keys.
Create it in the Xebit VoiceKit admin console under Integrations → API Keys.
Update an appointment
/v1/appointments/{appointment_id}Requires appointments:write. Send only what you are changing; at least one field is required.
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 '{
"assigned_doctor": "Dr. Priya Sharma",
"notes": "Patient requested morning slot"
}'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={
"assigned_doctor": "Dr. Priya Sharma",
"notes": "Patient requested morning slot"
}
)
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({
assigned_doctor: "Dr. Priya Sharma",
notes: "Patient requested morning slot"
})
});
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 '{
"assigned_doctor": "Dr. Priya Sharma",
"notes": "Patient requested morning slot"
}'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={
"assigned_doctor": "Dr. Priya Sharma",
"notes": "Patient requested morning slot"
}
)
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({
assigned_doctor: "Dr. Priya Sharma",
notes: "Patient requested morning slot"
})
});
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": "Dr. Priya Sharma",
"status": "confirmed",
"external_reference_id": null,
"created_at": "2026-05-26T10:00:00.000Z",
"updated_at": "2026-05-26T11:00:00.000Z"
}
}Updatable fields
| Name | Type | Required | Description |
|---|---|---|---|
appointment_date | string | No | New ISO 8601 UTC date and time. Checked against availability, capacity and duplicate rules. |
status | string | No | confirmed, completed or cancelled. |
assigned_doctor | string | No | Name or identifier of the assigned doctor. |
notes | string | No | Free text notes on the appointment. |
session | string | No | "Morning", "Afternoon" or "Evening". |
batch | string | No | Batch label, for example "MA". |
Rescheduling
Passing appointment_date re-runs the same availability and capacity checks as creation, against the new time. If the new time fails, the request is rejected with OUTSIDE_AVAILABILITY, SLOT_FULL or DUPLICATE_BOOKING. Unless the same request also sets status, the appointment's status becomes "rescheduled" automatically.
Status transitions
Set status: "completed" when the visit has happened and status: "cancelled" to cancel. Cancelling Appointments covers the cancellation rules.
Error codes
| Status | Code | Cause |
|---|---|---|
400 | VALIDATION_ERROR | No valid fields were sent, or appointment_date is malformed. |
404 | NOT_FOUND | Appointment not found. |
409 | SLOT_FULL | The new time has no capacity left. |
409 | SLOT_INACTIVE | The new time's window is closed. |
409 | DUPLICATE_BOOKING | An active booking already exists for this patient, type and new date. |
422 | OUTSIDE_AVAILABILITY | The new time is not inside any configured window. |
422 | TOO_FAR_IN_ADVANCE | Appointments can be rescheduled at most 7 days ahead. |
403 | INSUFFICIENT_SCOPE | The key lacks the required scope. |