EMRDesk
Press / or Ctrl+K
Sign inPatient PortalGet started
EMRDesk
Sign in
Implementation guide

HL7 v2 file intake API

Receive HL7 v2 messages from labs, hospitals, and partner systems.

HL7 intake

Guide scope

MethodPOSTAccessreceiveAuthBearer key

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.