Fetch a Single Appointment — GET /appointments/{id}

The Get Appointment endpoint returns the complete record for a single appointment identified by its UUID. Use this endpoint when you need the full detail view of an appointment — including its current status, payment status, teleconsult URL (if applicable), and all timestamps. This is the canonical way to check whether a booking was confirmed, whether payment was received, or to retrieve the video link to share with a patient before a teleconsulta.

Request

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

string

required

The UUID of the appointment you want to retrieve. Appointment UUIDs are returned when you create an appointment or list appointments.

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

Appointment start time in ISO 8601 UTC format.

string

Appointment end time in ISO 8601 UTC format.

string

Appointment type: presencial or teleconsulta.

string

Current lifecycle status: scheduled, confirmed, cancelled, completed, or no_show.

string

Notes attached to the appointment. null if none were added.

string

Payment status for this appointment: pending, paid, or overdue.

string

The video room URL for the consultation. Only present when type is teleconsulta. null for presencial appointments.

string

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

string

Timestamp of the most recent update to this appointment (ISO 8601 UTC).

If you need to display the teleconsult_url to a patient, always fetch the appointment immediately before the call to ensure you have the latest URL — it can be regenerated if the room expires.

Example Request

curl --request GET \
  --url "https://api.bydoctor.com.br/v1/appointments/c3d4e5f6-a7b8-9012-cdef-123456789012" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json"

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-15T14:00:00Z",
  "ends_at": "2025-07-15T14:30:00Z",
  "type": "teleconsulta",
  "status": "confirmed",
  "notes": "Patient requested video call due to travel.",
  "payment_status": "pending",
  "teleconsult_url": "https://meet.bydoctor.com.br/room/c3d4e5f6",
  "created_at": "2025-07-01T10:15:30Z",
  "updated_at": "2025-07-02T08:44:00Z"
}

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

Appointments

Patients

Schedules & Availability

Payments

Webhooks

Fetch a Single Appointment — GET /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