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
| Field | Type | Description |
|---|---|---|
id | string | Opaque token identifying this patient (pat_ prefix). Stable across requests for the same patient, and what you pass to the appointments sub-resource below. |
firstName | string | Patient's first name. |
lastName | string | Patient's last name. |
gender | string | A FHIR Patient.gender code: male, female, other, or unknown. |
phone | string | Phone number. May be null. |
email | string | Email address. May be null. |
city | string | City of residence. May be null. |
zipCode | string | Postal code. May be null. |
country | string | Country of residence. May be null. |
createdAt | string | RFC 3339 UTC timestamp of when the patient record was created. |
List patients
Returns the equipe's patients, oldest first. No 31-day window limit applies here, unlike the appointments endpoints below.
Query parameters
| Parameter | Description |
|---|---|
search | Matches patients whose name contains the text, or whose codice fiscale, email or phone is exactly the text. 3 to 100 characters. |
codice_fiscale | Filter to an exact Italian fiscal code. Use this to look up a patient you already know; the fiscal code itself is never returned. |
created_since | RFC 3339 UTC timestamp. Only patients created on or after this time. |
created_before | RFC 3339 UTC timestamp. Only patients created before this time. Must be after created_since if both are given. |
limit | Page size, 1–100. 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 filters as the request that returned it, or it's rejected with 400. |
curl "https://api.platform.arzamed.com/api/v1/patients?search=verdi&limit=50" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response
{
"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
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
| Field | Type | Description |
|---|---|---|
practitionerId required | string | Handle of the practitioner who creates the patient, from resolving a practitioner. |
firstName required | string | Up to 50 characters. |
lastName required | string | Up to 50 characters. |
gender required | string | male, female or other. |
phone required | string | Country prefix and number, digits only, up to 12, for example 393331234567. A leading +, spaces and dashes are removed. |
codiceFiscale | string | Italian fiscal code, 16 letters and digits. Required unless allowNoFiscalCode is true. Used to find an existing patient, and never returned. |
allowNoFiscalCode | boolean | true 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. |
email | string | Up to 255 characters. |
dateOfBirth | string | A date like 1985-08-01, not in the future. |
address | string | Street and number, up to 255 characters. |
city | string | Up to 50 characters. |
zipCode | string | Up to 10 characters. |
country | string | ISO country code, for example IT. |
Any other field is refused with 400. Clinical data, insurance and notes are managed in the ArzaMed app.
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
{
"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
| Status | Cause |
|---|---|
400 | A 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. |
401 | Missing or invalid Authorization header, or the token has expired. |
403 | The 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. |
409 | A 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. |
422 | No codiceFiscale and allowNoFiscalCode is not true; or the Idempotency-Key was already used for a different patient. |
429 | The equipe has exceeded its plan's monthly call quota, or its per-minute rate limit. See Usage & quotas. |
502 | An internal service returned an unexpected error. Before retrying, check whether the patient was created with GET /api/v1/patients?codice_fiscale=. |
503 | A downstream service is temporarily unreachable and nothing was saved. Retry later with the same Idempotency-Key. |
504 | An 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
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 "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
| Status | Cause |
|---|---|
400 | On /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. |
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. |
404 | On 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. |
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. |