API OVERVIEW

Pagination

Request IDs

Versioning

Rate Limits

Idempotency

Restricted endpoints

Going to production

CLINIC

Clinic

Retrieve a clinic

Idempotency

Some create endpoints support idempotent retries. This lets you safely retry a request (for example, after a network timeout) without accidentally creating a duplicate record.

Making an idempotent request

Send an Idempotency-Key header with a unique value (for example, a UUID or a request ID from your own system):

Idempotency-Key: ehr-request-abc

We store the key together with the request path and a hash of the request body. If you retry the exact same request with the same key, we return the original response instead of processing it again.

Responses

  • Same key, same request body, same endpoint: the original response is replayed with the same status code and body it returned the first time.

  • Same key, different request body (or a different resource on the same endpoint, e.g. a different patient_id): the request is rejected with a 422 and an idempotency_conflict error, since the key has already been used for a different request:

    {
  "error": "idempotency_conflict",
  "message": "A different request was already submitted with this idempotency key."
}

  • Same key, original request still in progress: the request is rejected with a 409 and a request_in_progress error. Retry after a short delay:

    {
  "error": "request_in_progress",
  "message": "A request with this idempotency key is currently being processed. Retry after a moment."
}

Notes

  • The Idempotency-Key header is optional. Requests sent without it are processed normally and are not deduplicated.
  • Idempotency keys are scoped per clinic. If your integration sends requests on behalf of more than one clinic, the same key can be reused across different clinics without conflict.
  • Check each endpoint's documentation to confirm whether it supports the Idempotency-Key header.