---
title: "Operator agenda (date range)"
method: GET
path: "/api/operators/crm/agenda"
tags: ["operators"]
---

# Operator agenda (date range)

`GET /api/operators/crm/agenda`

## Request

- Base URL: `https://api.corabea.it` (the document declares no server; this is the origin it was published from)
- URL: `https://api.corabea.it/api/operators/crm/agenda`
- Auth: HTTP bearer

Appointments and published, not-yet-booked availability. Defaults to the authenticated operator; an admin or coordinator must name one with `operator_id`, customer care may. A `patient_id` with no `operator_id` is the patient's own calendar across every expert; with a `patient_id` the range may be left out for the patient's whole history (narrowed to `operator_id` when given), which carries no availability.

## Query parameters

- `from_date` string, date-time, nullable: Range start, ISO 8601 (inclusive).
- `to_date` string, date-time, nullable: Range end, ISO 8601 (exclusive).
- `mode` string, nullable: Filter appointments by mode: 'online' or 'in_person'.
- `type_code` string[]: Filter appointments by raw appointment type code(s); 'family' matches the family-session flag instead.
- `patient_id` string, uuid, nullable: Filter appointments by patient.
- `payment_from` string, date, nullable: Keep appointments paid on/after this day (Europe/Rome).
- `payment_to` string, date, nullable: Keep appointments paid on/before this day (Europe/Rome).
- `status` string[]: Keep only appointments in these statuses (DA_FARE, FATTO, DA_RIPROGRAMMARE, ANNULLATO, RIMBORSATO); every status when left out.
- `operator_id` string, uuid, nullable: Required for admin and coordinator callers; customer care may name any operator; anyone else only their own operator record.

## Response `200`

Successful Response

- OperatorAgendaResponse: Operator agenda for a date range: appointments + published openings. Date-range counterpart of :class:`OperatorTodayResponse`; backs the CRM Agenda calendar and list views.
  - `from_date` string, nullable: Range start, ISO 8601 (inclusive); null for a patient's whole history.
  - `to_date` string, nullable: Range end, ISO 8601 (exclusive); null for a patient's whole history.
  - `appointment_count` integer
  - `appointments` OperatorAgendaAppointment[]
    - `id` string, uuid, required
    - `patient_id` string, uuid, nullable
    - `start_at` string, required: Appointment start, ISO 8601
    - `duration_minutes` integer, nullable
    - `type_code` string, nullable
    - `call_modality` 'phone' | 'video', nullable: Effective call mode, including the patient's phone/video choice.
    - `is_family` boolean: A family session; type_code stays the discipline's own INCONTRO_*.
    - `is_valuation` boolean: A valuation session; type_code stays the discipline's own INCONTRO_*.
    - `status` string, nullable
    - `patient_name` string, nullable
    - `operator_label` string, nullable: Owning operator display name (the agenda's operator).
    - `operator_id` string, uuid, nullable: Owning operator's id (the agenda's operator).
    - `operator_profession` string, nullable: PSICOLOGO or NUTRIZIONISTA — the owning operator's discipline, so the calendar can pick a row's icon without resolving the operator against a separate list. Constant across one agenda, since an agenda belongs to a single expert.
    - `in_person` boolean: True when the expert attends physically (either in-person sub-mode).
    - `location_type` string, nullable: Stored location type. With in_person it separates the two sub-modes: in_person = expert and patient in the room, online = expert only.
    - `location` string, nullable
    - `paid` boolean: True when the appointment is paid (succeeded or via coupon).
    - `consent` boolean: False only when informed consent is explicitly missing/invalid.
    - `meeting_link` string, nullable
    - `payment_status` string, nullable
    - `payment_completed_at` string, nullable: When the payment went through, ISO 8601.
    - `refund_pending` boolean: A refund was requested and Stripe has not confirmed it yet.
    - `payment_discount_code` string, nullable
    - `paid_with_coupon` boolean: Paid with a coupon: neither refundable nor transferable.
    - `payment_method` string, nullable: How it was paid; free and welfare-voucher payments cannot be transferred.
    - `has_history` boolean: Whether the appointment has status, reschedule or payment history.
    - `psi_state` string, nullable
    - `nutri_state` string, nullable
  - `availability_slots` OperatorTodayAvailabilitySlot[]: Published, not-yet-booked openings in the range — the 'Disponibilità' rows.
    - `id` string, uuid, required
    - `start_at` string, required: Slot start, ISO 8601
    - `duration_minutes` integer, nullable
    - `in_person` boolean
    - `also_in_person` boolean: A customer care's opening offered both online and in presenza at its clinic.
    - `location` string, nullable
    - `room_availability_id` string, uuid, nullable: Room slot an operator availability is tied to.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-07** `0be19a2c25c2`: 1 info
  - added the optional property `appointments/items/call_modality` to the response with the `200` status
- **2026-10-07** `babe5287135b`: 2 info
  - added the optional property `appointments/items/payment_discount_code` to the response with the `200` status
  - added the optional property `availability_slots/items/also_in_person` to the response with the `200` status
- **2026-10-01** `6108ff351838`: 2 info
  - added the optional property `appointments/items/payment_completed_at` to the response with the `200` status
  - added the optional property `appointments/items/refund_pending` to the response with the `200` status
- **2026-09-29** `c612195c91c3`: 1 info
  - added the new optional `query` request parameter `status`
- **2026-09-25** `a39eb6aada31`: 2 info
  - added the optional property `appointments/items/paid_with_coupon` to the response with the `200` status
  - added the optional property `appointments/items/payment_method` to the response with the `200` status

[Operation history](https://skmtc.dev/corabea/apis/corabea-api/changes/api/operators/crm/agenda/get.md)

---

[API](https://skmtc.dev/corabea/apis/corabea-api.md) · [All operations](https://skmtc.dev/corabea/apis/corabea-api/llms.txt) · [OpenAPI document](https://skmtc.dev/corabea/apis/corabea-api/revisions/4a8dd89893b8?raw)