HL7 v2 file intake API

Use the HL7 v2 file intake API to receive messages from labs, hospitals, and other partner systems.

Endpoint

POST /receiveHl7Interop

Security model

Send x-api-key with the required HL7 ingestion scope.

Accepted formats

• JSON body with message and optional routing metadata.
• text/plain payloads for direct HL7 message posts.
• File names ending in .hl7 or .txt are treated as message payloads when supplied.

Parsed segments

• MSH
• PID
• PV1
• DG1
• OBR
• OBX
• RXA
• AL1
• NTE

Request example

{
  "patientId": "patient_12345",
  "fileName": "oru-r01.hl7",
  "message": "MSH|^~\\&|LAB|HOSPITAL|EMRDESK|POPULARIS|202603071030||ORU^R01|MSG00001|P|2.5\nPID|1||MRN12345||DOE^JANE\nOBR|1||ORD-88||24323-8^CMP^LN\nOBX|1|TX|24323-8^CMP^LN||All values normal"
}

Response headers

• x-request-id is returned for tracing and can be supplied by the caller.
• x-ratelimit-limit shows the request limit for the current key.
• x-ratelimit-remaining shows requests left in the current window.
• x-ratelimit-reset shows when the current rate-limit window resets.

What gets normalized

• Stores the source message and parsed metadata.
• Normalizes diagnosis/problem segments when present.
• Normalizes order and observation segments when present.
• Normalizes immunization segments when present.
• Flags missing required message structure for review.

When to use it

Use this endpoint for inbound HL7 feeds. For connector packets, see OpenMRN intake; for outbound HL7, see HL7 chart export.

Common errors

• 401: the API key is missing, revoked, or invalid.
• 403: the key does not include HL7 intake scope.
• 429: the partner key exceeded its configured rate limit.