ArzaMed API
Build integrations on top of ArzaMed — the cloud platform that powers scheduling, medical records and billing for equipes and healthcare professionals.
The ArzaMed external API lets partner systems work with live data in an equipe's ArzaMed account: read practitioners, their appointments and patient contact details, add patients, and book, change or cancel visits. Each equipe generates its own API credentials and authorises your system to access their data using the OAuth2 client credentials flow.
Credentials are issued per equipe. Each equipe generates their own client_id and client_secret from their ArzaMed account. Contact the equipe's administrator to obtain credentials before you start.
Choose your path
Quickstart
From credentials to your first authenticated response in under five minutes.
Authentication
How to exchange credentials for an access token and attach it to requests.
API Reference
Endpoint details, parameters and example responses.
Conventions
Error codes and other shared behaviours.
Base URL & versioning
All API requests are made over HTTPS to a single, versioned base URL. The current version is v1.
Breaking changes are released under a new major version. Additive, backwards-compatible changes (new fields, new endpoints) may ship within the current version. In this case, write integrations that ignore unknown JSON fields.
A sandbox environment is available at https://api-uat.nextgen.arzamed.com/api/v1. Use it for integration testing with UAT credentials provided by the equipe's ArzaMed administrator.
Requests & responses
The API follows REST conventions: resource-oriented URLs, standard HTTP verbs, and JSON responses. All requests must include a valid Authorization header.
curl https://api.platform.arzamed.com/api/v1/practitioners \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Successful responses use standard 2xx status codes and return a JSON body. List endpoints return a plain JSON array:
[
{
"name": "Dr. Marco Bianchi",
"profileImage": "https://assets.arzamed.com/photos/abc123.jpg"
}
]
Writes
Endpoints that create or change data (POST, PATCH) need a token with the write scope (see Scopes), a JSON body sent with Content-Type: application/json, and an Idempotency-Key header:
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 '{ ... }'
Generate a new Idempotency-Key for every new operation (a UUID works: letters, digits, - and _, up to 255 characters), and send the same key again when you retry that operation, for example after a timeout. For 24 hours, a retry with the same key and the same body returns the first answer instead of making the change twice. While the first request is still running, a retry gets 409; the same key with a different body gets 422. If a request fails, you can retry it with the same key.
A body field the endpoint doesn't accept is refused with 400, and detail lists the accepted fields, so nothing you send is silently ignored.
Errors
ArzaMed uses conventional HTTP status codes to indicate the outcome of a request.
| Status | Meaning |
|---|---|
400 | Bad Request — a parameter or body field is missing or invalid. These errors use the problem+json shape shown below. |
401 | Unauthorized — missing or invalid access token. |
403 | Forbidden — the token does not have access to this resource (wrong equipe, the API key has been revoked, disabled, or has expired, or the token lacks the scope the request needs), or on a write, the practitioner isn't allowed to make the change. |
404 | Not Found — the resource or id is not in your equipe. A malformed id or one of another equipe look the same. |
409 | Conflict — on a write: the time is not available, or a request with the same Idempotency-Key is still running. |
422 | Unprocessable — on a write: the change isn't possible in the resource's current state, or the Idempotency-Key was already used for a different request. |
429 | Too Many Requests — the equipe has exceeded its plan's monthly call quota, or its per-minute rate limit. See Usage & quotas. |
502 | Bad Gateway — an internal service this request depends on returned an error. Retry with exponential back-off. |
503 | Service Unavailable — a downstream service is temporarily unreachable. Retry with exponential back-off. |
504 | Gateway Timeout — an internal service this request depends on timed out. Retry with exponential back-off. |
Errors raised before a request reaches an endpoint (401, 403 for the API key or scope, the general 429) and failures of the read endpoints (502, 503, 504) share this shape, only the message text changes:
{
"error": "Service unavailable"
}
Validation errors (a malformed parameter or body field, a date range that's too wide, an expired handle, or the resolve endpoint's own rate limit), lookups that find nothing (404), and the errors of the write endpoints (409, 422, 502, 503, and 403 when the practitioner isn't allowed) use a different, more detailed shape: RFC 7807 application/problem+json. Check the Content-Type header to tell which shape you got.
{
"title": "Invalid date range",
"status": 400,
"detail": "'start' must be before 'end'.",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
detail is written to be shown to a developer, not an end user — it names the exact parameter and rule that failed. Include requestId when contacting support about a specific failed request.