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

PATCH/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"
  }'
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"
  }'

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": "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: when false, 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

StatusCodeCause
404NOT_FOUNDAppointment not found.
403INSUFFICIENT_SCOPEThe key lacks the required scope.