Practitioners

Retrieve the list of active practitioners registered at an equipe, and resolve one to access their calendar.

The practitioners endpoints return the active medical staff for the equipe associated with your API credentials. No equipe identifier is required in the URL — the API resolves it from your access token automatically.

Need one practitioner's appointments? Resolving a practitioner here is the first step of the two-step calendar flow — see Calendar events.

The Practitioner object

FieldTypeDescription
namestringFull display name of the practitioner (first name + last name).
rolestringOne of doctor, nurse, office, admin.
profileImagestringPublic URL of the practitioner's profile photo. May be null if no photo has been uploaded.

List practitioners

GET /api/v1/practitioners

Returns all active doctors, nurses, office staff, and equipe administrators for the equipe. The response is a plain JSON array, ordered by the equipe's internal display order.

Equipe administrators are included as admin because a solo practice's only account is often set up as the admin rather than a separate doctor account.

Request

No request body. Authentication via Bearer token is required.

ParameterDescription
roleOptional. Filter to one of doctor, nurse, office, admin. Omit to return all four.
cURL
curl https://api.platform.arzamed.com/api/v1/practitioners \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

JSON · 200 OK
[
  {
    "name": "Dr. Marco Bianchi",
    "role": "doctor",
    "profileImage": "https://assets.arzamed.com/photos/a1b2c3.jpg"
  },
  {
    "name": "Sofia Ricci",
    "role": "nurse",
    "profileImage": null
  },
  {
    "name": "Luca Ferrari",
    "role": "office",
    "profileImage": "https://assets.arzamed.com/photos/g7h8i9.jpg"
  },
  {
    "name": "Dr. Elena Costa",
    "role": "admin",
    "profileImage": null
  }
]

Error responses

StatusCause
400Invalid role value. 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.
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

  • Only practitioners with an active account are included. Staff whose account has been blocked do not appear.
  • The name field is a pre-formatted display string. There are no separate first/last name fields in the external API.
  • profileImage is a direct public URL. No signing or credentials are needed to access it. Cache the URL as long as the token is valid; the resource is permanent and will not rotate.
  • The response contains no internal identifiers. They are never exposed to external callers.
  • A practitioner's role also travels with any handle you resolve for them, and is echoed back on each of their appointments as practitionerRole. See Calendar events.

Resolve a practitioner

GET /api/v1/practitioner

Looks up one practitioner (doctor, nurse, office staff, or equipe administrator) by email and exchanges them for a short-lived, opaque handle. The handle is not the practitioner's real internal id, which never leaves the platform. It's what you pass to the Calendar events endpoint, and it's step 1 of the two-step calendar flow.

This endpoint carries a tighter rate limit than the rest of the API, on top of the general per-equipe limit described in Usage & quotas. Build your integration to resolve a practitioner once and reuse the handle for the full 30 minutes, not to look one up on every request.

Query parameters

ParameterDescription
email requiredThe practitioner's email address, matched case-insensitively.
first_nameOptional. If supplied, must match (case-insensitive) or the lookup fails as not found.
last_nameOptional. Same matching behaviour as first_name.
cURL
curl "https://api.platform.arzamed.com/api/v1/practitioner?email=marco.bianchi%40example.com" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

JSON · 200 OK
{
  "practitionerId": "K7QRXNK3TFH2MZ8W",
  "expiresAt": "2026-09-01T13:04:00Z"
}

Despite the field name, practitionerId is the opaque handle, not a real identifier — it's random, valid for 30 minutes, and only resolvable by the API key that minted it. Request a new one once it expires.

Error responses

StatusCause
400Missing or malformed email. Uses the problem+json error shape.
404No active, exposed practitioner matches: wrong email, first_name/last_name didn't match, or the account's role isn't one of doctor, nurse, office, admin. Also problem+json. The response is deliberately identical in all of these cases, so callers can't use it to enumerate staff.
429This endpoint's own, tighter rate limit was exceeded (see the note above), separate from the general per-equipe limit. Also problem+json, distinct from the plain {"error":...} shape the general limit's 429 uses elsewhere.
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.