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

Base URL & versioning

All API requests are made over HTTPS to a single, versioned base URL. The current version is v1.

https://api.platform.arzamed.com/api/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
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:

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

StatusMeaning
400Bad Request — a parameter or body field is missing or invalid. These errors use the problem+json shape shown below.
401Unauthorized — missing or invalid access token.
403Forbidden — 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.
404Not Found — the resource or id is not in your equipe. A malformed id or one of another equipe look the same.
409Conflict — on a write: the time is not available, or a request with the same Idempotency-Key is still running.
422Unprocessable — 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.
429Too Many Requests — the equipe has exceeded its plan's monthly call quota, or its per-minute rate limit. See Usage & quotas.
502Bad Gateway — an internal service this request depends on returned an error. Retry with exponential back-off.
503Service Unavailable — a downstream service is temporarily unreachable. Retry with exponential back-off.
504Gateway 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:

JSON
{
  "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.

JSON · application/problem+json
{
  "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.