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

  1. GET /api/v1/practitioner?email=... — resolve the practitioner you want by email, get back an opaque handle valid for 30 minutes.
  2. 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

FieldTypeDescription
idstringOpaque 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.
typestringvisit or hospitalisation.
statusstringA FHIR Appointment.status code: proposed, booked, arrived, checked-in, fulfilled, cancelled, or noshow.
startTimestringStart of the appointment, RFC 3339 UTC (e.g. 2026-09-01T09:00:00Z).
endTimestringEnd of the appointment, RFC 3339 UTC.
practitionerNamestringDisplay name of the practitioner. Names only, no internal ids are included anywhere in the response.
practitionerRolestringOne 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.
patientNamestringDisplay name of the patient.
locationNamestringName of the room or location, if one is assigned. May be null.
updatedAtstringRFC 3339 UTC timestamp of the last change to this appointment — useful for sync/polling.

Get a practitioner's appointments

GET /api/v1/practitioners/{handle}/appointments

{handle} is the opaque value from resolving a practitioner — not a real practitioner id.

Query parameters

ParameterDescription
start requiredRFC 3339 UTC timestamp. Start of the window (inclusive). Must end in Z; a UTC offset such as +02:00 is rejected.
end requiredRFC 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.
typeRepeatable. Filter to one or both of visit, hospitalisation (lowercase). Defaults to both.
statusRepeatable. 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.
limitPage size, 1–500. Defaults to 100.
cursorOpaque 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
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

JSON · 200 OK
{
  "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

StatusCause
400The 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.
401Missing or invalid Authorization header, or the token has expired.
403The 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.
429The equipe has exceeded its plan's monthly call quota, or its per-minute rate limit. See Usage & quotas.
502An internal service this request depends on returned an error. Retry with exponential back-off.
503A downstream service is temporarily unreachable. Retry with exponential back-off.
504An 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 visit and hospitalisation appointments.