FHIR R4

Clive exposes a read-only FHIR R4 (4.0.1) view of members, appointments, consents and released lab results to partners, and can export a member's record as a FHIR collection Bundle. This document is the contract: what each FHIR element is built from, which codes are used, and what is deliberately left out. The code is in apps/api/src/features/fhir/ (mappers.ts builds the resources, codes.ts holds every code system and value map, schema.ts the structural validators).

Out of scope: writes of any kind, Encounter, Practitioner, Location, Organization, ServiceRequest, subscriptions, _history, _revinclude, chained search, and SMART-on-FHIR launch.

Endpoints

Base: /api/v1/fhir/r4

{type} is one of Patient, Appointment, Consent, DiagnosticReport, Observation. Any other method on these paths answers 405 with an OperationOutcome.

• Media type: every response is application/fhir+json; charset=utf-8.
• Errors: every non-2xx body is an OperationOutcome with one issue: issue.code from the FHIR IssueType value set (login 401, forbidden 403, not-found 404, invalid / not-supported 400, throttled 429, exception 500) and issue.details.text carrying the stable Clive error code partners can branch on (INVALID_TOKEN, INSUFFICIENT_SCOPE, CONSENT_REQUIRED, NOT_FOUND, ...). diagnostics is human-readable.
• Auth: OAuth 2.0 client credentials, the same clients and tokens as the partner API (POST /oauth/token, Authorization: Bearer ...). The per-client rate limit and revocation apply.
• Audit: every successful read and search writes an audit_logs row (action = READ, the API client as actor, details.fhir = resource type, details.interaction = read / search-type / search-include). Consent refusals are written by the consent gate (data_share_log and an audit_logs data_share entry).

Scopes

FHIR is another representation of the same records, so it uses the existing data scopes rather than a separate fhir:read scope (which would let a client holding only that scope read results it was never granted):

Consent gate

A read of one member's resource, or a search with patient= / subject=, answers 403 CONSENT_REQUIRED when the gate refuses. A search across members leaves out the members the gate refuses (the page may then hold fewer than _count entries; keep following next). Every decision, allowed or blocked, is written to data_share_log with event type fhir.<Resource>.<read|search>. Consent is read live, so a withdrawal stops the very next request.

Released results only

Only lab orders with status released (after review, via release_lab_order) and the results of those orders are visible. An unreleased, withheld or cancelled order, and its results, answer 404 on read exactly like an id that does not exist, and never appear in a search, an _include or an export. Released results can no longer be amended, so every exposed DiagnosticReport and Observation has status final.

Erased (deleted) and merged members are not exposed, nor is anything belonging to them.

Search parameters

Common to every type:

Per type:

Any other parameter is refused with 400 not-supported instead of being ignored, so a misspelt filter never widens a search.

Ordering and paging. Results are ordered by (meta.lastUpdated, id) ascending, so a search is also a change feed: page with _lastUpdated=ge<t>, follow link[relation=next] until it is absent, remember the last meta.lastUpdated, and resume from it. The Bundle has link self and (when there are more) next; total is not returned. entry.search.mode is match for matches and include for _included Observations.

Identifier and code systems

Clive-defined systems live under https://clivehealth.app/fhir. They are identifiers, not links, and never change.

Patient

From patients (+ decrypted encrypted_pii) and patient_external_ids.

Not exported: address, emergency contact, notes, blind indexes, encrypted blobs (parity with the Members API). When the PII cannot be decrypted the PII-derived elements are omitted, never guessed.

Appointment

From appointments.

Status map (our state machine → Appointment.status):

Search status=booked matches both scheduled and confirmed.

Consent

From consents (one row per member and purpose; history stays in consent_events and is not exposed as FHIR).

DiagnosticReport

From a released lab_orders row, its lab_order_items (→ lab_test_catalog) and its lab_results.

To get the report and its Observations in one call: GET /DiagnosticReport?_id=<id>&_include=DiagnosticReport:result (or ?patient=<id>&_include=DiagnosticReport:result). The included Observations are the ones result references.

Observation

From a lab_results row of a released order.

LOINC

LOINC codes live in the catalogue: lab_test_catalog.loinc_code for the panel and reference_range.analytes[].loinc per analyte, seeded for the global catalogue by 20261026400000_fhir.sql from LOINC_CODES in apps/api/src/features/labs/catalog.ts (a unit test keeps the two identical and checks every code's LOINC check digit).

The mapping is deliberately conservative: a code is used only where it is unambiguous for the units and specimen in our catalogue, e.g. the molar creatinine code 14682-9 (µmol/L), not the mass one. Covered: the full blood count (all 12 analytes, panel 58410-2), ESR, reticulocytes, PT/APTT/INR, ABO and Rh, HbA2/HbF, ferritin, iron studies, B12 and folate, sodium, potassium, chloride, creatinine, the liver panel (panel 24325-3), total/HDL cholesterol and triglycerides, fasting and random glucose, HbA1c (% and IFCC), uric acid, calcium, phosphate, magnesium, amylase, lipase, CK, LDH, CRP, hs-troponin I, NT-proBNP, TSH, free T4, FSH, LH, β-hCG, the urine dipstick (SG, pH, protein, leukocytes, nitrite), urine hCG, HBsAg, anti-HBs, anti-HCV, HIV Ag/Ab, RF, IgE, PSA, CEA, CA 125, AFP and SARS-CoV-2 RNA.

Local code only (by design, until the reporting method is known): eGFR (equation-specific codes), LDL and non-HDL cholesterol (direct vs calculated), urea in mmol/L, corrected calcium, OGTT time points, free T3, 25-OH vitamin D, cortisol, testosterone, prolactin and insulin in SI units, the urine albumin:creatinine ratio, HbA (adult), the remaining dipstick and microscopy fields, dengue, typhoid, H. pylori, syphilis, ANA, cultures, cytology, HPV, every veterinary panel, and every clinic's own catalogue entries.

Bundles

• searchset (API): id, meta.lastUpdated, timestamp, link (self, next), entry[] with fullUrl = <base>/<type>/<id> and search.mode.
• collection (export, below): entry[].fullUrl = urn:uuid:<id> (our ids are UUIDs), and references between entries are rewritten to those URNs so the Bundle resolves on its own.

Export (format: 'fhir')

POST /api/v1/exports (staff), POST /public/v1/exports (partner) and DSAR access requests accept format: "fhir":

• member scope: one collection Bundle (application/fhir+json, .json) with the Patient, their Appointments and Consents and, when the requester may see clinical content (view_results), one DiagnosticReport per released lab order with its Observations. Unreleased results are never exported in FHIR. Partner API exports never include clinical content (as for CSV/JSON).
• clinic scope: NDJSON (application/fhir+ndjson, .ndjson), one collection Bundle per line per member, with Patient and Appointments: the same records as the clinic CSV/JSON export.

row_counts on the export counts resources by type.