Booking appointments
Book, change and cancel visits, with the same treatments, locations and free slots the ArzaMed app uses.
Every change is made as a practitioner of the equipe, with that practitioner's permissions in ArzaMed: send their handle (the practitionerId from resolving a practitioner) in each request. What a practitioner can't do in the ArzaMed app, they can't do through the API either. A visit booked or changed through the API sends the same notifications as one booked in the app.
The POST and PATCH endpoints on this page need the write scope and an Idempotency-Key header. See Writes.
Typical flow
GET /api/v1/practitioner?email=...: resolve the practitioner who books.GET /api/v1/treatments?practitionerId=...andGET /api/v1/locations: choose a treatment and a location.GET /api/v1/practitioners/{handle}/availability: find a free slot.GET /api/v1/patients?codice_fiscale=..., or create the patient: get the patient'sid.POST /api/v1/patients/{id}/appointments: book the visit.
List treatments
The treatments that can be booked as a visit, as in the visit form of the ArzaMed app. With practitionerId, only the treatments that practitioner may perform.
Query parameters
| Parameter | Description |
|---|---|
practitionerId | Optional. A practitioner handle. |
curl "https://api.platform.arzamed.com/api/v1/treatments?practitionerId=K7QRXNK3TFH2MZ8W" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response
[
{
"id": "trt_zWKCZKAXaBJkpybganSNFc4IIhZ9wltX",
"name": "Visita di controllo",
"durationMinutes": 30
}
]
| Field | Type | Description |
|---|---|---|
id | string | Opaque token (trt_ prefix), stable for the same treatment. Send it as treatment. |
name | string | Name of the treatment. |
durationMinutes | integer | Usual length of the visit in minutes. May be null: then send an end when you book it. |
List locations
The equipe's active locations, as in the visit form of the ArzaMed app.
[
{
"id": "loc_a8w0FUCxy6CylypB8pIgEZove32_g3mb",
"name": "Studio 2",
"address": "Via Roma 1",
"city": "Rimini",
"zipCode": "47921",
"country": "IT"
}
]
| Field | Type | Description |
|---|---|---|
id | string | Opaque token (loc_ prefix), stable for the same location. Send it as location. |
name | string | Name of the location. |
address | string | Street address. May be null, like the city, postal code and country. |
Find free slots
Free slots of one practitioner, the same "next available slots" the ArzaMed app shows: the practitioner's availability minus their visits, hospitalisations, internal activities and holidays, cut into slots of the length you ask for.
Query parameters
| Parameter | Description |
|---|---|
start required | RFC 3339 UTC timestamp with a trailing Z. Start of the window. |
end required | Same format. End of the window, after start and at most 31 days after it. |
duration | Slot length in minutes, 5–1440. |
treatment | A trt_ id: the slots take that treatment's length. Send either duration or treatment. |
curl "https://api.platform.arzamed.com/api/v1/practitioners/K7QRXNK3TFH2MZ8W/availability?start=2026-11-02T00:00:00Z&end=2026-11-03T00:00:00Z&duration=30" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response
[
{ "start": "2026-11-02T08:00:00Z", "end": "2026-11-02T08:30:00Z" },
{ "start": "2026-11-02T08:30:00Z", "end": "2026-11-02T09:00:00Z" }
]
An empty array means there is no free slot in the window, for example because the practitioner has no availability set for those days.
Error responses
| Status | Cause |
|---|---|
400 | The handle has expired; start/end are missing, not RFC 3339 with a trailing Z, out of order or more than 31 days apart; neither duration nor treatment was sent; duration is out of range; or the treatment has no length (send duration). Uses the problem+json error shape. |
404 | The treatment is not in your equipe, or the practitioner can't perform it. |
Book an appointment
Books a visit for the patient {id} (a pat_ id) in the practitioner's calendar. The practitioner needs the permission to modify the equipe's visits in ArzaMed. Responds 201 with the new appointment, as the Appointment object with status booked; its id is what you change or cancel it with.
Body
| Field | Type | Description |
|---|---|---|
practitionerId required | string | Handle of the practitioner who books. The visit goes in their calendar. |
treatment required | string | A trt_ id from List treatments. |
location required | string | A loc_ id from List locations. |
start required | string | RFC 3339 UTC timestamp with a trailing Z, in the future. |
end | string | Same format, after start and at most 24 hours after it. May be left out when the treatment has a length. |
notes | string | Up to 255 characters, shown on the visit in ArzaMed. |
confirmOutsideAvailability | boolean | Default false: a time outside the practitioner's availability, or already taken, is refused with 409. true books it anyway, like confirming the warning in the ArzaMed app. |
curl -X POST "https://api.platform.arzamed.com/api/v1/patients/pat_QW1hbmRhIFZlcmRpIGV4YW1wbGU/appointments" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 0b6d3c2e-51f4-4a8b-a1d7-9e3f6c2b8a40" \ -d '{ "practitionerId": "K7QRXNK3TFH2MZ8W", "treatment": "trt_zWKCZKAXaBJkpybganSNFc4IIhZ9wltX", "location": "loc_a8w0FUCxy6CylypB8pIgEZove32_g3mb", "start": "2026-11-02T08:00:00Z", "notes": "Prima visita" }'
Response
{
"id": "evt_8f2KzQ1RmN0vLp3vXA2vRw",
"type": "visit",
"status": "booked",
"startTime": "2026-11-02T08:00:00Z",
"endTime": "2026-11-02T08:30:00Z",
"practitionerName": "Dr. Marco Bianchi",
"practitionerRole": null,
"patientName": "Giulia Verdi",
"locationName": "Studio 2",
"updatedAt": "2026-10-27T10:30:12Z"
}
Change an appointment
{id} is the appointment's evt_ id. Only the fields you send change, and you must send at least one change. Only visits that are still booked can be changed. The practitioner must be allowed to change the visit in ArzaMed: their own visits (created by or for them) with the permission to modify their own visits, or any visit with the permission to modify the equipe's visits. Responds 200 with the updated appointment.
Body
| Field | Type | Description |
|---|---|---|
practitionerId required | string | Handle of the practitioner who makes the change. |
newPractitionerId | string | Handle of the practitioner the visit moves to. |
treatment | string | A new trt_ id. |
location | string | A new loc_ id. |
start | string | A new start, in the future. The rules are the same as when booking. |
end | string | A new end. Send it together with start. |
notes | string | New notes, up to 255 characters. |
confirmOutsideAvailability | boolean | As when booking, for a new time. |
curl -X PATCH "https://api.platform.arzamed.com/api/v1/appointments/evt_8f2KzQ1RmN0vLp3vXA2vRw" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 7c9e4b1a-2f6d-4d3e-b8a5-1c0f9e7d6b52" \ -d '{ "practitionerId": "K7QRXNK3TFH2MZ8W", "start": "2026-11-02T09:00:00Z" }'
Cancel an appointment
Cancels a booked visit. The visit is kept with status cancelled, as in the ArzaMed app. Cancelling an appointment that is already cancelled returns it again, so a retry is safe. Responds 200 with the appointment.
Body
| Field | Type | Description |
|---|---|---|
practitionerId required | string | Handle of the practitioner who cancels. Same permissions as changing the visit. |
by | string | patient (default) or clinic: who cancelled the visit, as recorded in ArzaMed. |
curl -X POST "https://api.platform.arzamed.com/api/v1/appointments/evt_8f2KzQ1RmN0vLp3vXA2vRw/cancel" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 3e8f1d7c-6a2b-4c9e-8d1f-5b7a0c3e9d64" \ -d '{ "practitionerId": "K7QRXNK3TFH2MZ8W", "by": "patient" }'
Error responses for booking, changing and cancelling
| Status | Cause |
|---|---|
400 | A field is missing, invalid or not accepted; a time is not RFC 3339 with a trailing Z or is not in the future; end is not after start or is more than 24 hours after it; there is no end and the treatment has no length; notes is too long; a change sends nothing to change; a handle has expired; or the Idempotency-Key header is missing or invalid. Uses the problem+json error shape. |
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 lacks the permission ArzaMed requires for this change. |
404 | An id in the path or the body is not in your equipe, or the practitioner may not change this appointment. A malformed id or one of another equipe look the same. |
409 | The time is outside the practitioner's availability or already taken: choose a free slot, or send confirmOutsideAvailability: true to book it anyway. Or a request with the same Idempotency-Key is still running. |
422 | The appointment can't be changed: it's a hospitalisation, or the visit is no longer booked. Or the Idempotency-Key was already used for a different request. |
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 change was made with GET /api/v1/patients/{id}/appointments. |
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. |
Notes
- Only visits can be booked, changed or cancelled. Hospitalisations can be read but not changed through the API.
- Times are UTC. ArzaMed shows them in the equipe's local time.
- Recurring visits, and statuses other than
bookedandcancelled(for example marking a patient as arrived), are managed in the ArzaMed app.