Patients

List and add an equipe's patients, and retrieve one patient's calendar.

Patients belong to the equipe directly, so there's no email-based resolve step like there is for practitioners: list patients to get their id, then use that id to fetch their appointments. Only names and contact details are returned: no codice fiscale or birth details, and nothing clinical (no notes, allergies, insurance, or assigned staff).

The Patient object

FieldTypeDescription
idstringOpaque token identifying this patient (pat_ prefix). Stable across requests for the same patient, and what you pass to the appointments sub-resource below.
firstNamestringPatient's first name.
lastNamestringPatient's last name.
genderstringA FHIR Patient.gender code: male, female, other, or unknown.
phonestringPhone number. May be null.
emailstringEmail address. May be null.
citystringCity of residence. May be null.
zipCodestringPostal code. May be null.
countrystringCountry of residence. May be null.
createdAtstringRFC 3339 UTC timestamp of when the patient record was created.

List patients

GET /api/v1/patients

Returns the equipe's patients, oldest first. No 31-day window limit applies here, unlike the appointments endpoints below.

Query parameters

ParameterDescription
searchMatches patients whose name contains the text, or whose codice fiscale, email or phone is exactly the text. 3 to 100 characters.
codice_fiscaleFilter to an exact Italian fiscal code. Use this to look up a patient you already know; the fiscal code itself is never returned.
created_sinceRFC 3339 UTC timestamp. Only patients created on or after this time.
created_beforeRFC 3339 UTC timestamp. Only patients created before this time. Must be after created_since if both are given.
limitPage size, 1–100. 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 filters as the request that returned it, or it's rejected with 400.
cURL
curl "https://api.platform.arzamed.com/api/v1/patients?search=verdi&limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

JSON · 200 OK
{
  "data": [
    {
      "id": "pat_QW1hbmRhIFZlcmRpIGV4YW1wbGU",
      "firstName": "Giulia",
      "lastName": "Verdi",
      "gender": "female",
      "phone": "+39 333 1234567",
      "email": "giulia.verdi@example.com",
      "city": "Rimini",
      "zipCode": "47921",
      "country": "Italy",
      "createdAt": "2025-11-03T10:22:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": false,
    "nextCursor": null
  }
}

Create a patient

POST /api/v1/patients

Finds or creates a patient. If an active patient with the same codiceFiscale already exists in the equipe, it is returned unchanged with 200; otherwise a new patient is created and returned with 201. Either way the response is the Patient object above, and its id is what you book appointments for.

The patient is created as a practitioner of the equipe (their handle in practitionerId), who becomes the patient's creator and assigned user. The practitioner needs the permission to modify the equipe's patients in ArzaMed. Needs the write scope and an Idempotency-Key, see Writes.

Body

FieldTypeDescription
practitionerId requiredstringHandle of the practitioner who creates the patient, from resolving a practitioner.
firstName requiredstringUp to 50 characters.
lastName requiredstringUp to 50 characters.
gender requiredstringmale, female or other.
phone requiredstringCountry prefix and number, digits only, up to 12, for example 393331234567. A leading +, spaces and dashes are removed.
codiceFiscalestringItalian fiscal code, 16 letters and digits. Required unless allowNoFiscalCode is true. Used to find an existing patient, and never returned.
allowNoFiscalCodebooleantrue to create a patient without a fiscal code. Such a patient can't be matched to an existing one, so every call creates a new patient.
emailstringUp to 255 characters.
dateOfBirthstringA date like 1985-08-01, not in the future.
addressstringStreet and number, up to 255 characters.
citystringUp to 50 characters.
zipCodestringUp to 10 characters.
countrystringISO country code, for example IT.

Any other field is refused with 400. Clinical data, insurance and notes are managed in the ArzaMed app.

cURL
curl -X POST "https://api.platform.arzamed.com/api/v1/patients" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1c2a9e-7b3d-4e8a-9c61-2d5f0b8e3a71" \
  -d '{
    "practitionerId": "K7QRXNK3TFH2MZ8W",
    "firstName": "Giulia",
    "lastName": "Verdi",
    "gender": "female",
    "phone": "393331234567",
    "codiceFiscale": "VRDGLI85M41H294X",
    "email": "giulia.verdi@example.com",
    "dateOfBirth": "1985-08-01",
    "city": "Rimini",
    "zipCode": "47921",
    "country": "IT"
  }'

Response

JSON · 201 Created
{
  "id": "pat_QW1hbmRhIFZlcmRpIGV4YW1wbGU",
  "firstName": "Giulia",
  "lastName": "Verdi",
  "gender": "female",
  "phone": "393331234567",
  "email": "giulia.verdi@example.com",
  "city": "Rimini",
  "zipCode": "47921",
  "country": "IT",
  "createdAt": "2026-10-27T10:22:00Z"
}

Error responses for creating a patient

StatusCause
400A field is missing, invalid, too long or not accepted; the practitioner handle has expired; or the Idempotency-Key header is missing or invalid. Uses the problem+json error shape, check detail for which field.
401Missing or invalid Authorization header, or the token has expired.
403The token lacks the write scope, the API key is revoked, disabled or expired, or the practitioner isn't active in the equipe or may not create patients.
409A request with the same Idempotency-Key is still running, or another request is creating a patient with the same fiscal code at this moment. Retry shortly.
422No codiceFiscale and allowNoFiscalCode is not true; or the Idempotency-Key was already used for a different patient.
429The equipe has exceeded its plan's monthly call quota, or its per-minute rate limit. See Usage & quotas.
502An internal service returned an unexpected error. Before retrying, check whether the patient was created with GET /api/v1/patients?codice_fiscale=.
503A downstream service is temporarily unreachable and nothing was saved. Retry later with the same Idempotency-Key.
504An internal service timed out. The change may or may not have been saved: retry with the same Idempotency-Key, which never applies it twice.

Get a patient's appointments

GET /api/v1/patients/{id}/appointments

Same query parameters, pagination, and RFC 3339 rules as the practitioner appointments endpoint: start and end (required, trailing Z, 31-day cap), type, status (FHIR codes), limit, cursor. {id} is a patient id from the list above, not a handle.

cURL
curl "https://api.platform.arzamed.com/api/v1/patients/pat_QW1hbmRhIFZlcmRpIGV4YW1wbGU/appointments?start=2026-09-01T00:00:00Z&end=2026-09-08T00:00:00Z" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response is the same Appointment object, except practitionerRole is always null here: a patient's appointments can be with different practitioners in different roles, so there's no single role to attach to the whole response.

Error responses

StatusCause
400On /patients: created_since is not before created_before, or limit/cursor is invalid. On the appointments sub-resource: the same validation as Calendar events. Uses the problem+json error shape.
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.
404On the appointments sub-resource: {id} doesn't decode to a patient of this equipe. A malformed, tampered, or wrong-equipe id all look identical, so this can't be used to probe for valid ids.
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.