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

  1. GET /api/v1/practitioner?email=...: resolve the practitioner who books.
  2. GET /api/v1/treatments?practitionerId=... and GET /api/v1/locations: choose a treatment and a location.
  3. GET /api/v1/practitioners/{handle}/availability: find a free slot.
  4. GET /api/v1/patients?codice_fiscale=..., or create the patient: get the patient's id.
  5. POST /api/v1/patients/{id}/appointments: book the visit.

List treatments

GET /api/v1/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

ParameterDescription
practitionerIdOptional. A practitioner handle.
cURL
curl "https://api.platform.arzamed.com/api/v1/treatments?practitionerId=K7QRXNK3TFH2MZ8W" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

JSON · 200 OK
[
  {
    "id": "trt_zWKCZKAXaBJkpybganSNFc4IIhZ9wltX",
    "name": "Visita di controllo",
    "durationMinutes": 30
  }
]
FieldTypeDescription
idstringOpaque token (trt_ prefix), stable for the same treatment. Send it as treatment.
namestringName of the treatment.
durationMinutesintegerUsual length of the visit in minutes. May be null: then send an end when you book it.

List locations

GET /api/v1/locations

The equipe's active locations, as in the visit form of the ArzaMed app.

JSON · 200 OK
[
  {
    "id": "loc_a8w0FUCxy6CylypB8pIgEZove32_g3mb",
    "name": "Studio 2",
    "address": "Via Roma 1",
    "city": "Rimini",
    "zipCode": "47921",
    "country": "IT"
  }
]
FieldTypeDescription
idstringOpaque token (loc_ prefix), stable for the same location. Send it as location.
namestringName of the location.
addressstringStreet address. May be null, like the city, postal code and country.

Find free slots

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

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

ParameterDescription
start requiredRFC 3339 UTC timestamp with a trailing Z. Start of the window.
end requiredSame format. End of the window, after start and at most 31 days after it.
durationSlot length in minutes, 5–1440.
treatmentA trt_ id: the slots take that treatment's length. Send either duration or treatment.
cURL
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

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

StatusCause
400The 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.
404The treatment is not in your equipe, or the practitioner can't perform it.

Book an appointment

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

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

FieldTypeDescription
practitionerId requiredstringHandle of the practitioner who books. The visit goes in their calendar.
treatment requiredstringA trt_ id from List treatments.
location requiredstringA loc_ id from List locations.
start requiredstringRFC 3339 UTC timestamp with a trailing Z, in the future.
endstringSame format, after start and at most 24 hours after it. May be left out when the treatment has a length.
notesstringUp to 255 characters, shown on the visit in ArzaMed.
confirmOutsideAvailabilitybooleanDefault 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
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

JSON · 201 Created
{
  "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

PATCH /api/v1/appointments/{id}

{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

FieldTypeDescription
practitionerId requiredstringHandle of the practitioner who makes the change.
newPractitionerIdstringHandle of the practitioner the visit moves to.
treatmentstringA new trt_ id.
locationstringA new loc_ id.
startstringA new start, in the future. The rules are the same as when booking.
endstringA new end. Send it together with start.
notesstringNew notes, up to 255 characters.
confirmOutsideAvailabilitybooleanAs when booking, for a new time.
cURL
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

POST /api/v1/appointments/{id}/cancel

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

FieldTypeDescription
practitionerId requiredstringHandle of the practitioner who cancels. Same permissions as changing the visit.
bystringpatient (default) or clinic: who cancelled the visit, as recorded in ArzaMed.
cURL
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

StatusCause
400A 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.
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 lacks the permission ArzaMed requires for this change.
404An 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.
409The 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.
422The 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.
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 change was made with GET /api/v1/patients/{id}/appointments.
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.

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 booked and cancelled (for example marking a patient as arrived), are managed in the ArzaMed app.