Treatment authorities

A prescriber's approval for the clinic's injectors. Read them with treatment_authorities:read. A registered prescribing-authority provider puts its own with one idempotent PUT per version.

A treatment authority is a prescriber's written approval for a clinic's injectors to give named medicines, at named areas, up to named amounts, for a period. Claro's own screening and the clinic's prescribers write them (source: claro). So can an outside screening service, a prescribing-authority provider such as Fresh OS (source: fresh_os). The nurse sees one pool at the chair.

Read them#

GET /treatment-authorities lists the clinic's authorities, whoever wrote them, oldest change first. Filter by patient, status (pending, active, expired, revoked, consumed) or source, and sync with updated_since. GET /treatment-authorities/{id} reads one (ta_…).

• treatment_authorities:read: status, type, validity, version and the prescriber (name, profession, registrations; never a prescriber number).
• Also patients:read: which patient, your printed numbers (references) and the consult.
• Also clinical content: items (each medicine at each area, with its decision and amounts), the conditions and the revocation reason.
• expired is worked out from valid_until. It does not change updated_at.

Put your own: providers only#

Writing an authority changes what a nurse may legally give, so a scope is never enough. You need all three:

1. Registration. Claro registers your credential (an API key or OAuth client) as a provider for your source. It is never self-serve: ask us.
2. The clinic's choice. The clinic chooses you to provide its treatment authorities.
3. treatment_authorities:write, and an account that sees the clinic's patients.

Anyone else gets 403 not_authority_provider, and nothing is written. On the sandbox, your own test key is already registered, for your sandbox clinic only.

Your source is yours. Only your credentials create links in it, so a patient linked to your ID is one you linked (422 source_reserved for anyone else).

One PUT per version#

PUT /api/public/v1/treatment-authorities/by-external-id/fresh_os/ta-1056770
Authorization: Bearer claro_sk_test_au_…
Idempotency-Key: 6f1c2d9e-0b7a-4d8e-9a51-3c2f7e8b1a04
Content-Type: application/json

{
  "patient_external_id": {"source": "fresh_os", "id": "8d1f9c"},
  "version": 3,
  "authority_type": "standing",
  "status": "active",
  "decided_at": "2026-11-03T00:12:00Z",
  "valid_until": "2027-05-03T00:12:00Z",
  "references": {"prescription_number": "1056770"},
  "prescriber": {
    "name": "Dr Aisha Malhi",
    "profession": "doctor",
    "registrations": [{"authority": "ahpra", "number": "MED0001234567"}]
  },
  "lines": [
    {"line_id": "li_1", "decision": "approved",
     "medicine": {"artg_id": "195530", "name": "Botox 100U"},
     "areas": [{"area": "glabella", "quantity": 20, "unit": "units", "route": "needle"}]},
    {"line_id": "li_2", "decision": "declined",
     "medicine": {"name": "Juvederm Volbella XC"},
     "areas": [{"area": "lips_body", "quantity": 1, "unit": "ml"}],
     "decision_note": "Two weeks since last filler."}
  ],
  "conditions": "Avoid treatment if active cold sore."
}

• The patient is patient (pat_…) or patient_external_id, in your own source and already linked with PUT /patients/by-external-id/{source}/{external_id}. An unknown patient is 422 patient_unknown.
• Send the whole authority every time. A higher version amends it. Items are matched by line_id and area, so what was given under them stays counted.
• Decisions: approved, approved_with_conditions (with conditions), declined, changes_requested, deferred. Only the first two cover a dose. The rest are kept and shown.
• Mapping. A medicine is matched by ARTG ID first (GET /medicines?artg_id=), an area by slug (GET /treatment-areas). A line Claro cannot map is kept with your text, listed in warnings, and never covers a dose until a clinician confirms it. Units are never converted.
• Validity is yours. valid_until is required once active, and Claro never changes it.
• status: pending says a consult is under way. It covers nothing.

Revoke#

POST /treatment-authorities/by-external-id/{source}/{external_id}/revoke with version (higher), reason and optionally revoked_at. Doses already recorded under it stand.

At the chair#

• A Claro prescriber who injects always records under their own prescription. Your approvals are for the clinic's nurses.
• When your approval and the clinic's own both cover a dose, the nurse picks. The latest decided is the default.
• One side's change never alters the other's.
• What the nurse gives comes back to you in the drug register.