Lab connector: how a laboratory report in HL7 v2, CSV or JSON becomes FHIR Observations in one request

A laboratory has one job in an integration: get the report into the patient's record without retyping, without losing the reference range, and without inventing a format nobody else reads. The Anpheros lab connector takes the report as the laboratory already produces it, HL7 v2, CSV or JSON, and turns every result into a FHIR Observation with a LOINC code, a unit, a reference range, a date and the laboratory named as performer. This guide is the contract.

One request

POST /v1/patients/{patient_id}/labs/import
Authorization: Bearer <project key>
Content-Type: text/csv | x-application/hl7-v2+er7 | application/json
X-Anpheros-Source-System: labx        (optional; recorded in Provenance)
Idempotency-Key: <report id>          (optional; a retry returns the same answer)

The response says what happened:

{"created": 3, "skipped": 0, "unmapped": ["Marker foarte rar"], "warnings": [],
 "observations": [{"id": "…", "marker": "TSH", "code": "3016-3", "system": "http://loinc.org",
                   "value": 2.1, "unit": "mUI/L", "date": "2026-09-01"}]}

Formats

HL7 v2 ORU^R01, as ER7 text. OBX-3 is the identifier (code^text^LN is LOINC; a local code is kept as the lab's own code), OBX-5 the value, OBX-6 the unit, OBX-7 the reference range, OBX-8 the abnormal flag (becomes interpretation), OBX-11 the status, OBX-14 or OBR-7 the date. MSH-4 names the sending facility, which becomes the performer; OBR-3 and MSH-10 become the report id in Provenance. Pending, deleted or wrong results (I, X, D, W) and OBX segments without a value do not become Observations and are named in warnings.

CSV with a header row; separators , ; or tab, decimal comma accepted, dates ISO, DD.MM.YYYY or DD/MM/YYYY. Recognised columns in Romanian or English: marker, value, unit, reference range (70-100, <5, >3.5) or ref_low/ref_high, date, optional LOINC code, note. A CSV carries no laboratory, so the performer is missing unless you send X-Anpheros-Acting-As.

Analiza;Rezultat;UM;Interval de referinta;Data
Hemoglobina glicozilata (HbA1c);6,4;%;4,0-5,6;01.09.2026
TSH;2,1;mUI/L;0,4-4,0;01.09.2026

JSON when you already have structured data: {"date": "2026-09-01", "origin": "report-77", "laboratory": "Synevo", "items": [{"marker": "TSH", "value": 2.1, "unit": "mUI/L", "ref_low": 0.4, "ref_high": 4.0, "code": "3016-3"}]}.

Mapping rules that matter

• LOINC when given, otherwise by name. Names are matched against LOINC names and synonyms in Romanian and English. A name that matches several concepts, or carries a qualifier the concept does not have (urine, non-HDL, free, ratio), is not guessed: it keeps the lab's code under urn:anpheros:lab-code and appears in unmapped, so you can improve the mapping on your side. Send LOINC codes whenever you have them.
• Values are never converted. Urea and urea nitrogen are different codes; LDL direct and LDL calculated are different codes; glucose from serum and from capillary blood are different codes. The connector picks the right one from the name and the method, and leaves the number alone.
• Times keep their zone. A v2 time with an offset is kept; without one, the offset of MSH-7 is used with a warning; with none anywhere, only the date is stored. CSV times carry no zone and are stored as dates.
• Idempotent. Send the same report twice with the same Idempotency-Key and you get the same answer and no duplicates.
• Provenance on every result: the source system, the report id and the performer, as the HL7 Europe Laboratory Report requires.

What the patient sees

The results appear in the person's record and, if they use Anpheros Daily, on their phone as they arrive, with the reference range and the trend over previous reports. Nothing to scan, nothing to retype. If a result is abnormal the person sees the flag; the app does not interpret it.

Testing

The sandbox is free and the synthetic patients already have lab history. Post a report to one of them and read it back:

curl -X POST "$BASE/v1/patients/$PID/labs/import" -H "Authorization: Bearer $KEY" \
     -H "Content-Type: text/csv" --data-binary @report.csv
curl "$BASE/fhir/R4/Observation?patient=$PID&category=laboratory&_sort=-date" -H "Authorization: Bearer $KEY"

The full specification, including the HL7 Europe conformance notes, is at developers.anpheros.com/guides/lab-connector.

Frequently asked questions

Do we have to change what our LIS produces?

No. Send the ORU^R01 message or the CSV export as it is. If you can add LOINC codes, do; otherwise the connector maps by name and tells you what it could not map.

What about results you cannot map?

They are stored with the laboratory's own code and the exact text from the report, so nothing is lost, and listed in unmapped so you can add a LOINC code next time.

Are reference ranges and abnormal flags kept?

Yes: the range goes to referenceRange, the flag to interpretation, the unit is stored as UCUM, and the value is never converted.

Can a laboratory send results for a patient it did not create?

Only under the person's consent, or as the organisation the project acts for with X-Anpheros-Acting-As. A project sees the patients it created; everything else requires a grant.

Is there a cost for the integration?

The sandbox is free. Production starts at €49 a month per organisation, with the first month free; see pricing.