Regions

Australia and the United States are separate deployments, each at its own host. A key, and every ID it sees, belongs to one.

Base URLs#

A key names its region in its prefix. Send it to that region's base URL. Every response names its region in the x-claro-realm header.

The wrong region#

A key sent to the other region is refused before anything is looked up:

HTTP/1.1 421 Misdirected Request

{
  "error": {
    "type": "invalid_request_error",
    "code": "wrong_region",
    "message": "This API key belongs to the US region, which this server does not serve. Send it to https://api-us.claro.clinic.",
    "param": "https://api-us.claro.clinic",
    "request_id": "GOODd6zOX1oQKHIAAEOx"
  }
}

• param holds the base URL to use instead. Fix your configuration rather than redirecting at run time.
• It is a 421, not a 401: the key may be perfectly good. Don't discard it.
• An OAuth token has no region in it. Sent to the wrong region, it is simply unknown there: 401 invalid_credential.

One region per credential#

• Each region has its own servers and its own database.
• The API never returns another region's records, and never merges them.

An integration that serves clinics in both regions holds one credential per clinic, and the key's prefix tells it which base URL to use.

IDs are region-scoped#

IDs are opaque strings with a type prefix: clinic_, org_, prac_, pat_, appt_, whsub_. Store and compare them as strings. Never parse them.

An Australian ID sent to the US base URL is simply not found: 404 resource_missing. If you keep records from both regions in one table, key them on region and ID together.

What differs by region#

The contract is the same code in both regions. The data reflects each country:

• Practitioner registrations. registrations[].authority is ahpra in Australia and npi in the US.
• Addresses. state and postal_code hold the local form: a state and postcode in Australia, a state and ZIP code in the US.
• Error messages use the region's spelling. Branch on type and code, which never change.

Government identifiers are never returned in either region. See data classes.