Developers
One door into the national record: an OpenHIE mediator speaking FHIR R4. It authenticates the caller, gates on patient consent, and appends to a hash-chained log, including when it refuses.
Getting started
The server describes itself. GET /metadata returns a CapabilityStatement with no token, and cannot drift from the server because the server generates it.
- 01
Read GET /metadata. No token needed.
- 02
Register your application and receive credentials.
- 03
Authorise with OAuth 2.0 and present a bearer token.
- 04
Send THOS-Purpose on every request. Consent is gated and every call is logged, including refusals.
Operations
- GET /metadata
- CapabilityStatement. What this server supports, from the server.
- GET /fhir/{type}/{id}
- Read one resource
- GET /fhir/{type}/{id}/_history/{version}
- Read an earlier version
- GET /fhir/{type}?…
- Search, returns a Bundle
- POST /fhir/{type}
- Create
- PUT /fhir/{type}/{id}
- Update, versioned
- POST /fhir
- Transaction Bundle
- POST /fhir/Patient/$match
- Probabilistic match against the Client Registry
- POST /fhir/Patient/$register
- Register a citizen at the counter
- GET /fhir/Patient/{id}/$demographics
- Registry demographics and their history
- GET /audit?patient=&limit=
- The audit trail for one patient
- GET /audit/$verify
- Walk the hash chain. Authority role.
18 resource types: Patient, Encounter, Observation, Condition, MedicationRequest, DiagnosticReport, ServiceRequest, Specimen, Appointment, Communication, Consent, AllergyIntolerance, Immunization, Procedure, Practitioner, PractitionerRole, Organization, Location.
The rules a call meets
Under Tanzanian law health data belongs to the facility that holds it. Consent to share is the facility’s and the patient’s, and every read is recorded.
- 01
Authentication. A bearer token, or 401.
- 02
Role. Citizen, clinician, facility administrator, authority. A citizen writes nothing clinical.
- 03
Licence. Holding the clinician role is not enough. Clinical writes need a verified licence.
- 04
Consent. Reads inside the patient compartment are gated, and a provider cannot issue consent on a patient’s behalf.
- 05
Audit. Every call is appended to a hash-chained log, including the refusals.
Request headers
- authorization
- Bearer token. Required everywhere except /metadata.
- thos-purpose
- Why you are asking. Recorded on the audit row. "emergency" is break-glass and is marked as such.
- thos-consent
- The consent grant relied on, where one was obtained out of band.
- idempotency-key
- Replay protection on writes.
Errors
Every error is a FHIR OperationOutcome. The reason names the rule that refused, never the record behind it.
- 400
- The request is malformed.
- 401
- No token, or the token is not valid.
- 403
- Role, licence or consent refused it. The reason says which.
- 404
- No such resource.
- 405
- That method is not served on that path.
- 422
- A resource type this server does not support.
- 500
- A fault here. Nothing internal is disclosed.
- 503
- A dependency is unavailable.
Contact
Application registration is arranged with the operator: hello@laetoli.tz.
Security reports: /.well-known/security.txt. Design system: /design.