Connecting the laboratory system to Neolung

1. Address and key
The engine calls Neolung over HTTPS, outbound from the trust: no port or VPN to open. Each request carries the organisation's key, which an admin creates in Neolung, in its Authorization header.

Address and header:
https://app.neolung.io/api/integration/v1/hl7v2
Authorization: Bearer <key>

2. Test the connection
Neolung answers 200 when the key works. The admin sees the check in Neolung, in Settings, Integration.

Request:
curl -H "Authorization: Bearer <key>" 'https://app.neolung.io/api/integration/v1/check'

3. Send each new specimen
One OML^O21 (2.5 and later) or ORM^O01 (2.3, 2.4) per lab number, in the body of a POST, segments separated by carriage returns or line feeds. Neolung answers with an ACK: AA, or AE or AR with the reason in words.

Request:
curl -X POST -H "Authorization: Bearer <key>" -H "Content-Type: x-application/hl7-v2+er7" --data-binary @specimen.hl7 'https://app.neolung.io/api/integration/v1/hl7v2'

specimen.hl7:
MSH|^~\&|LIMS|LAB|NEOLUNG|NEOLUNG|20261026090000||OML^O21^OML_O21|MSG00001|T|2.5.1
ORC|NW|PLACER1|ZZ26-00001
OBR|1|PLACER1|ZZ26-00001|HISTO^Histology^L
SPM|1|^ZZ26-00001||LOBE^Right upper lobectomy^L

4. Collect each signed report
Every minute, GET the oldest report waiting: an ORU^R01 (2.5.1, or 2.4 with ?version=2.4), or 204 when none waits. File it, then POST its ACK (AA filed, AE couldn't file), MSA-2 the report's MSH-10. The same report comes until it is acknowledged.

Request:
curl -H "Authorization: Bearer <key>" 'https://app.neolung.io/api/integration/v1/hl7v2'

Acknowledgement:
curl -X POST -H "Authorization: Bearer <key>" -H "Content-Type: x-application/hl7-v2+er7" --data-binary @ack.hl7 'https://app.neolung.io/api/integration/v1/hl7v2'

ack.hl7:
MSH|^~\&|LIMS|LAB|NEOLUNG|NEOLUNG|20261026091000||ACK^R01^ACK|ACK00001|T|2.5.1
MSA|AA|<MSH-10 of the report>

5. Test messages first
Until the organisation is approved for patient data in Neolung, send messages marked as test (MSH-11 T): Neolung refuses production ones.

6. What Neolung reads
Only the lab number, the specimen types and the requester's and site's codes. Neolung never reads the patient, clinical details or notes, and never keeps them.