HL7 v2 to FHIR R4 Mapping Reference — A Complete Segment-by-Segment Guide

If you've worked in healthcare integration for any length of time, you've hit this problem. You have a system that speaks HL7 v2. You have another system that speaks FHIR R4. Somewhere between them you need to translate one to the other, and the official documentation reads like it was written for people who already know the answer.

This is the reference we wish existed when we started doing this work. Every common HL7 v2 segment, mapped to its FHIR R4 equivalent, with code examples you can adapt directly. Bookmark it. Send it to your team. Use it as the source of truth when someone on a standup says “wait, what's MSH supposed to map to?”

This guide assumes basic familiarity with both standards. If HL7 v2 segments are still new, start with HL7 v2 message structure explained, and for the FHIR side see the FHIR R4 integration complete guide. Backed by the engineers who deliver Mirth Connect support for US healthcare organizations.

The official IHE and HL7 mapping documents will tell you that PID maps to Patient, OBX maps to Observation, and PV1 maps to Encounter. That's true but incomplete.

The real complexity isn't in the segment-to-resource mapping. It's in three things the docs gloss over.

First, HL7 v2 is positional and FHIR is named. PID-5 is the patient's name because it's in the fifth position of the PID segment, not because it has a label. FHIR's Patient.nameis named explicitly. Anywhere you have field-level transformations, you're translating between positional thinking and named-property thinking, and that's where most bugs live.

Second, HL7 v2 carries identity inline and FHIR carries identity by reference.In HL7, the patient's name appears in every message that mentions them. In FHIR, the patient is a separate resource and every message references them by URL. Translating from inline-identity to reference-identity means you need to either look up or create the patient resource before you can create the observation that points to them.

Third, HL7 v2 is a stream of messages and FHIR is a model of resources. A single HL7 v2 ORUmessage containing 5 lab results becomes, in FHIR, a Bundle containing 1 Patient + 1 Encounter + 1 ServiceRequest + 5 Observations + (potentially) 1 DiagnosticReport that references all the observations. The cardinality doesn't match.

Keep all three of these tensions in mind as you read the rest of this reference. Most mapping bugs trace back to one of them.

Before getting into segment-by-segment detail, internalize this:

HL7 v2 message = a verb.“An admission happened.” “A lab result is ready.” “An appointment was scheduled.” The message is event-oriented.

FHIR resource = a noun.“Here is a patient.” “Here is an observation.” “Here is an encounter.” The resource is state-oriented.

When you map HL7 to FHIR, you are translating verbs into nouns. The event (“an admission happened”) becomes a set of resources (“here is the patient, here is the encounter, here is the practitioner involved”).

This is why every HL7 message typically becomes a FHIR Bundle — a collection of resources representing the state described by the event.

MSH (Message Header)does not map to a FHIR resource directly. Instead, it informs the Bundle's metadata.

• MSH-7 (Date/Time of Message) → Bundle.timestamp
• MSH-9 (Message Type) → informs the choice of Bundle type and what resources to include
• MSH-10 (Message Control ID) → Bundle.identifier
• MSH-3 (Sending Application) → Bundle.meta.source or a custom extension

EVN (Event Type) appears in ADT messages and similarly informs the Bundle context.

• EVN-2 (Recorded Date/Time) → Encounter.period.start for admissions
• EVN-4 (Event Reason Code) → Encounter.reasonCode

PID (Patient Identification) maps to the Patient resource.

PD1 (Patient Additional Demographics) extends Patient with additional info.

• PD1-4 (Primary Care Provider) → Patient.generalPractitioner (reference to Practitioner)

NK1 (Next of Kin) maps to either a separate RelatedPerson resource or to Patient.contact.

• For tight relationships (emergency contact, guardian) → Patient.contact
• For full relationship modeling → RelatedPerson referencing the Patient

PV1 (Patient Visit) maps to the Encounter resource.

PV2 (Patient Visit Additional Info) provides additional context.

• PV2-3 (Admit Reason) → Encounter.reasonCode
• PV2-25 (Visit Priority Code) → Encounter.priority

For the full ADT context that drives most PV1 mapping work, see our HL7 ADT messages complete reference.

This is where most lab integrations live. Understanding this section well will solve 60% of your real-world mapping problems.

OBR (Observation Request) maps to ServiceRequest (and informs DiagnosticReport).

OBX (Observation/Result) maps to Observation.

OBX-2 value type mapping:

• NM (numeric) → Observation.valueQuantity
• ST (string) → Observation.valueString
• CE/CWE (coded entry) → Observation.valueCodeableConcept
• DT (date) → Observation.valueDateTime
• TM (time) → Observation.valueTime

ORC (Common Order) typically accompanies OBR and maps to additional ServiceRequest fields.

ORC-1 (Order Control) to ServiceRequest.status mapping:

• NW (New Order) → status=active, intent=order
• CA (Cancel Order) → status=revoked
• DC (Discontinue) → status=revoked
• HD (Hold Order) → status=on-hold
• RL (Release Previous Hold) → status=active

AL1 (Patient Allergy Information) maps to AllergyIntolerance.

Always link AllergyIntolerance back to the Patient via AllergyIntolerance.patient.

DG1 (Diagnosis) maps to Condition.

For Encounter-related diagnoses, also populate Condition.encounter.

PR1 (Procedures) maps to Procedure.

SIU messages carry appointment data and have a particularly complex translation. The high-level mapping:

SCH (Schedule Activity Information) maps to Appointment.

AIS (Appointment Information — Service) adds the type of service.

• AIS-3 (Universal Service ID) → Appointment.serviceType

AIG (Appointment Information — General Resource), AIL (Location), and AIP (Personnel) each describe participants in the appointment. These all become Appointment.participant entries with different participant.type values.

IN1 (Insurance) maps to Coverage.

IN2 and IN3 carry additional detail and are typically merged into the same Coverage resource or extensions.

Z-segments — segments starting with Z, like ZPD or ZIN — are the wild card of HL7 v2. They carry custom data that no standard exists for.

The FHIR equivalent is extensions. Every Z-field becomes an extension on the most relevant resource. For example, if ZPD-3 carries a custom patient attribute, it becomes:

{
  "resourceType": "Patient",
  "extension": [
    {
      "url": "https://yourorg.org/fhir/StructureDefinition/zpd-3-custom-attribute",
      "valueString": "..."
    }
  ]
}

Always define the StructureDefinitionfor any extension you create. Otherwise, you've moved the problem from “what does ZPD-3 mean” to “what does this extension mean” without solving anything.

Putting it all together, here's the structure for a typical ORU^R01 message (lab result) translated to FHIR.

Source HL7 v2 message:

MSH|...|...|ORU^R01|...
PID|...
PV1|...
OBR|...
OBX|1|NM|...
OBX|2|NM|...
OBX|3|CE|...

Destination FHIR Bundle:

{
  "resourceType": "Bundle",
  "type": "message",
  "timestamp": "2026-05-12T10:23:45Z",
  "identifier": { "value": "MSH-10 value here" },
  "entry": [
    { "resource": { "resourceType": "MessageHeader", "..." : "..." } },
    { "resource": { "resourceType": "Patient", "...": "..." } },
    { "resource": { "resourceType": "Encounter", "...": "..." } },
    { "resource": { "resourceType": "ServiceRequest", "...": "..." } },
    { "resource": { "resourceType": "DiagnosticReport", "...": "..." } },
    { "resource": { "resourceType": "Observation", "...": "..." } },
    { "resource": { "resourceType": "Observation", "...": "..." } },
    { "resource": { "resourceType": "Observation", "...": "..." } }
  ]
}

Resources reference each other via reference fields — Observation.subject points to Patient/[id], Observation.encounter points to Encounter/[id], and so on.

Six bugs we see in nearly every HL7 → FHIR pipeline we audit:

Mistake 1 — Treating Bundle as optional

New mappers sometimes try to send a single Observation resource directly instead of wrapping it in a Bundle. This fails most FHIR servers' validation because the receiving system has no context about the patient.

Mistake 2 — Hardcoding identifier systems

PID-3 carries identifiers from multiple authorities (MRN, SSN, payer IDs). Hardcoding "system": "urn:oid:1.2.3" means every patient ends up with the wrong identifier system. Map the HD component of PID-3 (the assigning authority) to the FHIR identifier.system.

Mistake 3 — Ignoring the difference between Patient.gender and PID-8

HL7 uses M/F/O/U. FHIR uses male/female/other/unknown. Don't pass through HL7's single-letter codes — FHIR validation will reject them.

Mistake 4 — Forgetting timezone information

HL7 v2 timestamps frequently omit timezone. FHIR's dateTimefields strongly prefer timezone-qualified ISO 8601. Decide on a default timezone (typically the sending facility's local time) and apply it consistently.

Mistake 5 — Creating duplicate Patient resources

Each new HL7 message contains the patient inline. If you create a new Patient resource for every message, you end up with thousands of duplicate Patients. Use conditional create (POST /Patient?identifier=...) or maintain a local identity map.

Mistake 6 — Using the wrong status mapping

OBX-11 has values like F (Final), C (Corrected), P (Preliminary). FHIR Observation.status uses different vocabulary (final, corrected, preliminary, amended). Always map through a translation table — don't pass the values through.

Useful tools when building HL7 to FHIR mappings:

• Mirth Connect (NextGen Connect). Our weapon of choice. Built-in HL7 parser, JavaScript and Groovy transformers, and you can ship FHIR resources via the HTTP Sender. We have a full walkthrough in how to build an HL7 interface in Mirth Connect.
• HAPI FHIR validator. Free, available as both a web tool and a CLI. Validates FHIR resources against any StructureDefinition. Use it on every Bundle you produce.
• Inferno test suite.ONC's official suite for testing FHIR conformance, especially relevant if you need to certify against USCDI requirements.
• LinuxForHealth FHIR Converter.Open-source tool from IBM that does pre-built HL7 to FHIR conversions. Useful as a reference implementation even if you don't use it in production — you can compare your output to its output.
• FHIR Mapping Language (FML).A formal DSL for expressing FHIR transformations. Powerful but heavyweight — most teams don't need it for basic HL7 to FHIR work.

If you're building a real HL7 to FHIR pipeline, the next pieces you'll need beyond this mapping reference are:

• A solid understanding of HL7 v2 message structure.
• Familiarity with HL7 ADT messages since they're the most common in real-world integration work.
• Working knowledge of FHIR bulk data if you're handling large datasets.
• A production-ready integration engine — Mirth Connect is what we recommend, and we've written about how to build an HL7 interface in Mirth Connect.

This reference will get you 80% of the way there. The remaining 20% — the timezone edge cases, the deduplication strategy, the error handling, the throughput tuning — is where most real projects spend most of their time.

If you'd rather not figure that out from scratch, we do this work for a living. Book a 30-minute scoping call and we'll tell you what we'd build and what it would cost.

Book a scoping call →

Or run our pricing calculator to estimate what an HL7 to FHIR project would cost based on your scope.

Prefer email? info@tactionsoft.com — we reply within 4 business hours.