Cancel an Existing Appointment — DELETE /appointments/{id}

The Cancel Appointment endpoint permanently transitions an appointment to the cancelled status. This is the only supported way to cancel a booking — the Update endpoint (PATCH) intentionally does not allow setting status to cancelled. You can optionally send a WhatsApp cancellation notice to the patient and supply a plain-text reason that is stored in the audit log for compliance and reporting purposes.

Request

DELETE https://api.bydoctor.com.br/v1/appointments/{id}

string

required

The UUID of the appointment to cancel.

boolean

default:false

When true, ByDoctor sends a WhatsApp cancellation message to the patient’s registered phone number after the appointment is successfully cancelled.

string

A plain-text description of why the appointment is being cancelled. This value is stored in the audit log and is visible to clinic staff in the dashboard. It is not sent to the patient. Example: "Patient requested reschedule".

Response Fields

string

The UUID of the appointment that was cancelled.

string

Always cancelled on a successful response.

string

The ISO 8601 UTC timestamp at which the cancellation was processed.

Cancellation is permanent — a cancelled appointment cannot be reinstated. If a patient simply did not attend their appointment, use Update Appointment (PATCH /appointments/{id}) with "status": "no_show" instead. This preserves the appointment record in a recoverable state and keeps your reporting accurate.

Example Request

curl --request DELETE \
  --url "https://api.bydoctor.com.br/v1/appointments/c3d4e5f6-a7b8-9012-cdef-123456789012?notify_patient=true&reason=Patient+requested+reschedule" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json"

Example Response (200 OK)

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "status": "cancelled",
  "cancelled_at": "2025-07-10T11:05:22Z"
}

Error Responses

400 Bad Request — The id path parameter is not a valid UUID format.

{
  "error": {
    "code": "validation_error",
    "message": "The value 'not-a-uuid' is not a valid appointment UUID."
  }
}

401 Unauthorized — Your API key is missing or invalid.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Provide a valid Bearer token in the Authorization header."
  }
}

404 Not Found — No appointment with the given ID exists in your clinic.

{
  "error": {
    "code": "not_found",
    "message": "No appointment found with id 'c3d4e5f6-a7b8-9012-cdef-123456789012'."
  }
}

422 Unprocessable Entity — The appointment cannot be cancelled because it is already in a terminal state (completed or cancelled).

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Appointment 'c3d4e5f6-a7b8-9012-cdef-123456789012' cannot be cancelled because its current status is 'completed'."
  }
}

Appointments

Patients

Schedules & Availability

Payments

Webhooks

Cancel an Existing Appointment — DELETE /appointments/{id}

Request

Response Fields

Example Request

Example Response (200 OK)

Error Responses

​Request

​Response Fields

​Example Request

​Example Response (200 OK)

​Error Responses

Request

Response Fields

Example Request

Example Response (200 OK)

Error Responses