Retrieve All Clinic Appointments — GET /appointments

The List Appointments endpoint returns a cursor-paginated collection of appointments belonging to your clinic. You can narrow results by date range, status, assigned professional, patient, or appointment type, and control the sort order to suit your workflow. Each response includes a meta object so you can determine whether more pages exist and fetch them using the cursor parameter.

Request

GET https://api.bydoctor.com.br/v1/appointments

integer

default:20

The maximum number of appointment records to return per page. Must be between 1 and 100.

string

An opaque pagination cursor returned in meta.next_cursor from a previous response. Pass this value to retrieve the next page of results. Omit on the first request.

string

Return only appointments whose starts_at is strictly after this ISO 8601 UTC timestamp. Example: 2025-06-01T00:00:00Z.

string

Return only appointments whose starts_at is strictly before this ISO 8601 UTC timestamp. Example: 2025-06-30T23:59:59Z.

string

Filter results to a single status. Accepted values: scheduled, confirmed, cancelled, completed, no_show.

string

Filter results to appointments assigned to this professional UUID.

string

Filter results to appointments linked to this patient UUID.

string

Filter results by appointment type. Accepted values: presencial, teleconsulta.

string

default:"created_at"

The field to sort results by. Accepted values: created_at, starts_at.

string

default:"desc"

The sort direction. Accepted values: asc, desc.

Response Fields

array

An array of appointment objects matching your query filters.

Show Appointment object

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 status: scheduled, confirmed, cancelled, completed, or no_show.

string

Optional notes attached to the appointment. May be null.

string

Payment status: pending, paid, or overdue.

string

Video room URL. Present only when type is teleconsulta. May be null.

string

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

string

Timestamp of the last update to the appointment (ISO 8601 UTC).

object

Pagination metadata for the current response.

Show Meta object

integer

Total number of appointments matching the current filters.

boolean

true if additional pages are available beyond the current response.

string

Cursor value to pass as the cursor query parameter to retrieve the next page. null when has_more is false.

Combine starts_after and starts_before to build a date-range report. For example, pass the first and last instant of a calendar month to pull a complete monthly schedule.

Example Request

curl --request GET \
  --url "https://api.bydoctor.com.br/v1/appointments?limit=2&starts_after=2025-06-01T00:00:00Z&starts_before=2025-06-30T23:59:59Z&status=confirmed&order=asc" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json"

Example Response (200 OK)

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "clinic_id": "clinic_01HX1234ABCD",
      "patient_id": "pat_01HX5678EFGH",
      "professional_id": "pro_01HX9012IJKL",
      "starts_at": "2025-06-10T09:00:00Z",
      "ends_at": "2025-06-10T09:30:00Z",
      "type": "presencial",
      "status": "confirmed",
      "notes": null,
      "payment_status": "pending",
      "teleconsult_url": null,
      "created_at": "2025-05-28T14:22:10Z",
      "updated_at": "2025-05-29T08:05:00Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "clinic_id": "clinic_01HX1234ABCD",
      "patient_id": "pat_01HX1111MNOP",
      "professional_id": "pro_01HX9012IJKL",
      "starts_at": "2025-06-10T10:00:00Z",
      "ends_at": "2025-06-10T10:45:00Z",
      "type": "teleconsulta",
      "status": "confirmed",
      "notes": "Follow-up from previous visit.",
      "payment_status": "paid",
      "teleconsult_url": "https://meet.bydoctor.com.br/room/b2c3d4e5",
      "created_at": "2025-05-30T11:00:00Z",
      "updated_at": "2025-05-30T11:00:00Z"
    }
  ],
  "meta": {
    "total": 48,
    "has_more": true,
    "next_cursor": "cursor_eyJpZCI6ImIyYzNkNGU1In0"
  }
}

Error Responses

400 Bad Request — A query parameter has an invalid value (for example, an unrecognised status or a malformed timestamp).

{
  "error": {
    "code": "validation_error",
    "message": "The value 'unknown' is not a valid status. Accepted values: scheduled, confirmed, cancelled, completed, no_show.",
    "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."
  }
}

Appointments

Patients

Schedules & Availability

Payments

Webhooks

Retrieve All Clinic Appointments — GET /appointments

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