Developers

Quickstart

Make an API key in Claro, then read your clinic and its patients.

1. Make an API key#

A clinic admin makes keys in Claro on the web.

  1. Go to Manage → Integrations and open Developer tools.
  2. On the API Keys tab, choose Create key.
  3. Name it after what will use it, for example "Patient sync".
  4. Under Scopes, pick Read patients for this guide. Pick as few as you need.
  5. Choose Create, copy the key, then choose I've saved it. Claro shows the key once.

A key belongs to one clinic, in one region. It acts as the admin who made it.

2. Know your key#

PrefixWorks against
claro_sk_live_au_Live clinics in Australia, at https://api-au.claro.clinic/api/public/v1
claro_sk_live_us_Live clinics in the US, at https://api-us.claro.clinic/api/public/v1
claro_sk_test_au_, claro_sk_test_us_The sandbox only. Self-serve sandbox access is coming.
claro_kOlder keys. They keep working where they always did.

The key names its region, so use the matching base URL. Sent to the other region, a key gets 421 wrong_region, with the right base URL in param. A test key on a live clinic gets 401 api_key_wrong_mode, and so does a live key on the sandbox.

Keep keys on a server. A key reads patient records. Never put one in a browser, a mobile app or a repository. Load it from an environment variable or a secrets manager.

3. Read your clinic#

export CLARO_API_KEY="claro_sk_live_au_..."   # paste your key

curl https://api-au.claro.clinic/api/public/v1/clinics \
  -H "Authorization: Bearer $CLARO_API_KEY"

With a claro_sk_live_us_ key, use https://api-us.claro.clinic/api/public/v1. Every key can read its own clinic, whatever its scopes.

{
  "object": "list",
  "data": [
    {
      "id": "clinic_k3v5tq2m7xw4b6n5r2c6hd3yja",
      "object": "clinic",
      "name": "Harbourside Skin",
      "org": { "id": "org_m2p6x5c3v7n3b5k4q6w2tr2zey", "name": "Harbourside Group" },
      "timezone": "Australia/Sydney",
      "country": "AU",
      "address": { "line1": "1 Example Street", "city": "Sydney", "state": "NSW", "postal_code": "2000", "country": "AU" },
      "phone": "+61 2 5550 0100",
      "email": "hello@example.com",
      "external_ids": [],
      "created_at": "2026-03-02T09:15:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

4. Read your patients#

curl "https://api-au.claro.clinic/api/public/v1/patients?limit=2" \
  -H "Authorization: Bearer $CLARO_API_KEY"
{
  "object": "list",
  "data": [
    {
      "id": "pat_3f2a9c1e7b4d4e0a9f6c2b8d5e1a7c3f",
      "object": "patient",
      "first_name": "Jordan",
      "middle_name": null,
      "last_name": "Sample",
      "preferred_name": null,
      "date_of_birth": "1988-04-12",
      "sex": "female",
      "gender": null,
      "gender_identity": "woman",
      "pronouns": "she/her",
      "email": "jordan.sample@example.com",
      "mobile": "+61491570006",
      "address": { "line1": null, "city": "Sydney", "state": "NSW", "postal_code": "2000" },
      "preferred_language": "English",
      "interpreter_required": false,
      "external_ids": [{ "source": "cliniko", "id": "100234" }],
      "created_at": "2026-05-20T01:02:03Z",
      "updated_at": "2026-10-29T04:05:06Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJyIjoicGF0aWVudHMi..."
}

An API key reaches one clinic, so it needs no Claro-Clinic header. has_more says there is another page: pass next_cursor back as cursor.

Next#