Update an Existing Appointment — PATCH /appointments/{id}

The Update Appointment endpoint allows you to modify an existing appointment using a partial update (PATCH semantics). You can reschedule by changing starts_at and ends_at, advance the lifecycle status to confirmed, completed, or no_show, or edit internal notes — all in a single request. Every field in the request body is optional; only the fields you include are changed. If you want the patient to receive a WhatsApp notification about the change, include "notify_patient": true in the request body.

Request

PATCH https://api.bydoctor.com.br/v1/appointments/{id} Content-Type: application/json

string

required

The UUID of the appointment to update.

string

New appointment start time as an ISO 8601 UTC timestamp. Must be provided together with ends_at when rescheduling.

string

New appointment end time as an ISO 8601 UTC timestamp. Must be strictly after the new starts_at.

string

Transition the appointment to a new lifecycle status. Accepted values: confirmed, completed, no_show. See the warning below regarding cancelled.

string

Replacement text for the notes field. Pass an empty string "" to clear existing notes.

boolean

default:false

When true, ByDoctor sends a WhatsApp update notification to the patient’s registered phone number after a successful update. Defaults to false so that routine administrative edits do not generate unwanted messages. This field is write-only and is not returned in responses.

Response Fields

string

Unique identifier for the appointment (UUID).

string

The ID of the clinic that owns this appointment.

string

The ID of the patient linked to this appointment.

string

The ID of the professional assigned to this appointment.

string

Current appointment start time in ISO 8601 UTC format (updated if rescheduled).

string

Current appointment end time in ISO 8601 UTC format (updated if rescheduled).

string

Appointment type: presencial or teleconsulta. Cannot be changed after creation.

string

The appointment’s current lifecycle status after the update.

string

The current notes after the update. null if none are set.

string

Current payment status: pending, paid, or overdue.

string

Video room URL. Present only when type is teleconsulta. null otherwise.

string

Timestamp when the appointment was originally created (ISO 8601 UTC).

string

Timestamp of this update (ISO 8601 UTC).

Setting status to cancelled via this endpoint is not permitted and will return a 400 Bad Request error. To cancel an appointment, use the Cancel Appointment endpoint (DELETE /appointments/{id}) instead. This separation ensures cancellations are audited correctly and that the optional WhatsApp cancellation notice is handled by the dedicated workflow.

Example Request — Reschedule an Appointment

curl --request PATCH \
  --url "https://api.bydoctor.com.br/v1/appointments/c3d4e5f6-a7b8-9012-cdef-123456789012" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "starts_at": "2025-07-22T10:00:00Z",
    "ends_at": "2025-07-22T10:30:00Z",
    "notes": "Rescheduled at patient request.",
    "notify_patient": true
  }'

Example Response (200 OK)

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "clinic_id": "clinic_01HX1234ABCD",
  "patient_id": "pat_01HX5678EFGH",
  "professional_id": "pro_01HX9012IJKL",
  "starts_at": "2025-07-22T10:00:00Z",
  "ends_at": "2025-07-22T10:30:00Z",
  "type": "teleconsulta",
  "status": "confirmed",
  "notes": "Rescheduled at patient request.",
  "payment_status": "pending",
  "teleconsult_url": "https://meet.bydoctor.com.br/room/c3d4e5f6",
  "created_at": "2025-07-01T10:15:30Z",
  "updated_at": "2025-07-10T09:30:00Z"
}

Error Responses

400 Bad Request — Invalid field value, including an attempt to set status to cancelled.

{
  "error": {
    "code": "validation_error",
    "message": "Setting status to 'cancelled' via PATCH is not allowed. Use DELETE /appointments/{id} to cancel an appointment.",
    "field": "status"
  }
}

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'."
  }
}

409 Conflict — The new time slot overlaps with another appointment for the same professional.

{
  "error": {
    "code": "time_slot_conflict",
    "message": "Professional 'pro_01HX9012IJKL' already has an appointment between 2025-07-22T10:00:00Z and 2025-07-22T10:30:00Z.",
    "conflicting_appointment_id": "d4e5f6a7-b8c9-0123-def0-234567890123"
  }
}

422 Unprocessable Entity — The request body is structurally valid but logically inconsistent (for example, ends_at is before or equal to starts_at).

{
  "error": {
    "code": "unprocessable_entity",
    "message": "'ends_at' must be strictly after 'starts_at'."
  }
}

Appointments

Patients

Schedules & Availability

Payments

Webhooks

Update an Existing Appointment — PATCH /appointments/{id}

Request

Response Fields

Example Request — Reschedule an Appointment

Example Response (200 OK)

Error Responses

​Request

​Response Fields

​Example Request — Reschedule an Appointment

​Example Response (200 OK)

​Error Responses

Request

Response Fields

Example Request — Reschedule an Appointment

Example Response (200 OK)

Error Responses