---
title: "Get appointments"
method: GET
path: "/api/appointments"
tags: ["appointments"]
---

# Get appointments

`GET /api/appointments`

Get appointments for the current patient, or for a specific patient if admin/supervisor/coordinator and patient_id is provided. Supervisor/coordinator: only patients in their supervised scope.

## Query parameters

- `limit` integer — Number of appointments to return (default: 20, most recent)
- `cursor` string, nullable — Cursor for the next page.
- `appointment_type` string, nullable — Filter by appointment type (CALL_CONOSCITIVA, CALL_GRATUITA, INCONTRO_PSICOLOGO, INCONTRO_NUTRIZIONISTA)
- `date_from` string, nullable — Filter by date range - start date (YYYY-MM-DD format, inclusive)
- `date_to` string, nullable — Filter by date range - end date (YYYY-MM-DD format, inclusive)
- `patient_id` string, uuid, nullable — Patient ID. If provided, returns that patient's appointments. If omitted, returns current user's appointments.
- `collapse_joint_appointments` boolean — Return a joint appointment as a single item instead of one row per expert. Set to false to get each expert's own appointment, as per-profession sections need. Ignored when patient_id is set.

## Response `200`

Successful Response

- AppointmentsListResponse — Appointments list response model.
  - `appointments` AppointmentResponse[], required — List of appointments
    - `id` string, required — Appointment UUID
    - `appointment_datetime` string, date-time, required — Appointment date and time
    - `duration_seconds` integer, required — Duration in seconds
    - `status` string, required — Appointment status
    - `appointment_type_code` string, required — Appointment type code
    - `operator_id` string, required — Operator UUID
    - `operator_first_name` string, required — Operator first name
    - `operator_last_name` string, required — Operator last name
    - `operator_email` string, nullable — Operator email
    - `operator_profession` string, nullable — Operator profession
    - `joint_operator_first_name` string, nullable — First name of the other expert, set only on a joint appointment merged into a single item
    - `joint_operator_last_name` string, nullable — Last name of the other expert, set only on a joint appointment merged into a single item
    - `joint_partially_paid` boolean — True when a joint appointment has one side paid and the other still to pay
    - `location` string, required — Appointment location (online/in_person)
    - `clinic_location_id` string, nullable — Clinic location UUID (null for online appointments)
    - `clinic_location` ClinicLocationResponse — Clinic location response model.
      - `id` string, required — Clinic location UUID
      - `name` string, required — Clinic location name
      - `address` string, nullable — Clinic location address
      - `city_id` integer, nullable — City ID
      - `city` CityInfo — City information model.
        - `id` integer, required — City ID
        - `name` string, required — City name
        - `province_code` string, nullable — Province code
      - `is_active` boolean, required — Whether the clinic location is active
    - `meeting_link` string, nullable — Meeting link if available
    - `meeting_link_status` string, required — Meeting link status: available, pending_consent, not_created, pending_consent_and_not_created, phone_call
    - `patient_cost` number, required — Patient cost in EUR
    - `payment_status` string, nullable — Payment status
    - `payment_completed_at` string, date-time, nullable — Payment completion timestamp
    - `payment_method` string, nullable — Payment method
    - `paid_with_coupon` boolean — True when payment succeeded using a coupon
    - `receipt_file_path` string, nullable — Receipt file path in storage, if available
    - `created_at` string, date-time, required — Appointment creation timestamp
  - `total` integer, required — Total number of appointments
  - `next_cursor` string, nullable — Cursor for the next page.
  - `has_more` boolean — Whether there are more results after this page
  - `has_valid_appointments` boolean, required — True if patient has at least one valid appointment (not cancelled or refunded)
  - `has_valid_call_conoscitiva` boolean, required — True if patient has a valid call conoscitiva (DA_FARE or FATTO, not cancelled/refunded)
  - `has_valid_call_gratuita` boolean, required — True if patient has a valid call informativa (DA_FARE, FATTO, or DA_RIPROGRAMMARE; not cancelled)
  - `has_completed_call_conoscitiva` boolean, required — True if patient has completed a call conoscitiva (FATTO, not cancelled/refunded)
  - `has_pending_call_conoscitiva` boolean, required — True if patient has a pending call conoscitiva (DA_FARE, not cancelled/refunded)
  - `can_book_repeat_call_conoscitiva` boolean — True if patient can book another call conoscitiva because both paths have been abandoned or concluded for the configured threshold
  - `has_completed_call_gratuita_questionnaire` boolean — True if patient has completed at least one call informativa questionnaire
  - `has_valid_appointments_by_profession` object, required — Dict with PSICOLOGO and NUTRIZIONISTA keys, True if has valid appointments for that profession
  - `is_first_appointment_by_profession` object, required — Dict with PSICOLOGO and NUTRIZIONISTA keys, True if this is the first appointment (no completed appointments)
  - `has_pending_appointments_by_profession` object, required — Dict with PSICOLOGO and NUTRIZIONISTA keys, True if has pending appointments (DA_FORE with payment not succeeded)
  - `has_assigned_psychologist` boolean, required — True if patient has an assigned psychologist
  - `has_assigned_nutritionist` boolean, required — True if patient has an assigned nutritionist

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/corabea/apis/corabea-api.md) · [All operations](https://skmtc.dev/corabea/apis/corabea-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/corabea/corabea-api/revisions/13c1bce1bdc4/schema)