Calendar events
Retrieve one practitioner's visits and hospitalisations for a date range.
Calendar access is practitioner-scoped, not equipe-wide — there's no endpoint that returns every appointment for the whole equipe at once. You fetch one practitioner's schedule at a time, in two steps: resolve the practitioner to a short-lived handle, then use that handle to page through their appointments.
Step 1 (resolving a practitioner) is documented on the Practitioners page — this page covers step 2.
The two-step flow
GET /api/v1/practitioner?email=...— resolve the practitioner you want by email, get back an opaque handle valid for 30 minutes.GET /api/v1/practitioners/{handle}/appointments— use that handle to page through their appointments, as many times as you need within the 30-minute window.
This keeps the practitioner's real internal id off the wire entirely. The handle is bound to the API key that created it and expires on its own after 30 minutes.
The Appointment object
| Field | Type | Description |
|---|---|---|
id | string | Opaque token identifying this appointment (evt_ prefix). Stable across requests for the same appointment, so it's safe to use as a dedup key. It does not reveal any internal identifier. |
type | string | visit or hospitalisation. |
status | string | A FHIR Appointment.status code: proposed, booked, arrived, checked-in, fulfilled, cancelled, or noshow. |
startTime | string | Start of the appointment, RFC 3339 UTC (e.g. 2026-09-01T09:00:00Z). |
endTime | string | End of the appointment, RFC 3339 UTC. |
practitionerName | string | Display name of the practitioner. Names only, no internal ids are included anywhere in the response. |
practitionerRole | string | One of doctor, nurse, office, admin, matching whichever practitioner this handle was resolved for. null on the patient appointments endpoint, where the practitioner varies per row. |
patientName | string | Display name of the patient. |
locationName | string | Name of the room or location, if one is assigned. May be null. |
updatedAt | string | RFC 3339 UTC timestamp of the last change to this appointment — useful for sync/polling. |
Get a practitioner's appointments
{handle} is the opaque value from resolving a practitioner — not a real practitioner id.
Query parameters
| Parameter | Description |
|---|---|
start required | RFC 3339 UTC timestamp. Start of the window (inclusive). Must end in Z; a UTC offset such as +02:00 is rejected. |
end required | RFC 3339 UTC timestamp, same Z requirement as start. End of the window (exclusive), the window is half-open [start, end). Must be after start, and at most 31 days after it. |
type | Repeatable. Filter to one or both of visit, hospitalisation (lowercase). Defaults to both. |
status | Repeatable. Filter to one or more FHIR Appointment.status codes, see the Appointment object above for the allowed values. Only those codes are accepted; other values are rejected with 400. Defaults to all statuses. |
limit | Page size, 1–500. Defaults to 100. |
cursor | Opaque pagination cursor from a previous response's pagination.nextCursor. Omit for the first page. Must be reused with the exact same start, end, type, and status as the request that returned it, or it's rejected with 400. |
curl "https://api.platform.arzamed.com/api/v1/practitioners/K7QRXNK3TFH2MZ8W/appointments?start=2026-09-01T00:00:00Z&end=2026-09-08T00:00:00Z&type=visit&status=booked&limit=50" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response
{
"data": [
{
"id": "evt_8f2KzQ1RmN0vLp3vXA2vRw",
"type": "visit",
"status": "booked",
"startTime": "2026-09-02T09:00:00Z",
"endTime": "2026-09-02T09:30:00Z",
"practitionerName": "Dr. Marco Bianchi",
"practitionerRole": "doctor",
"patientName": "Giulia Verdi",
"locationName": "Studio 2",
"updatedAt": "2026-08-30T15:12:04Z"
}
],
"pagination": {
"limit": 50,
"hasMore": true,
"nextCursor": "QT7mZ2xVn8pLk3wRtBs9Cd-eF1gHiJkLmNoPqRsTuVwXyZ"
}
}
Keep requesting with cursor set to the previous response's pagination.nextCursor until hasMore is false. nextCursor is null once there's nothing more to fetch.
Error responses
| Status | Cause |
|---|---|
400 | The handle has expired or is unknown; or start/end are missing, not RFC 3339 with a trailing Z, out of order, or more than 31 days apart; or type or limit is invalid; or status isn't one of the FHIR codes listed above; or cursor is malformed or was issued for a different start/end/type/status. Uses the problem+json error shape, check detail for which check failed. A handle error means step 1 needs to be repeated. |
401 | Missing or invalid Authorization header, or the token has expired. |
403 | The API key has been revoked, disabled, has expired (a key is valid for one year from when it's generated; on a paid plan it stays valid until the plan's renewal date plus 30 days), or is not registered in the system. |
429 | The equipe has exceeded its plan's monthly call quota, or its per-minute rate limit. See Usage & quotas. |
502 | An internal service this request depends on returned an error. Retry with exponential back-off. |
503 | A downstream service is temporarily unreachable. Retry with exponential back-off. |
504 | An internal service this request depends on timed out. Retry with exponential back-off. |
Notes
- A handle is single-equipe and single-API-key: it only resolves for the same credentials that minted it, and only for that one practitioner.
- There's no endpoint for a whole equipe's calendar — fetch practitioners individually. If you need everyone's schedule, resolve each practitioner and page through them in turn.
- Blocked time and other non-patient calendar entries are not included, only
visitandhospitalisationappointments.