HL7 v2 to FHIR Segment-to-Resource Mapping¶

When converting HL7 v2 messages into FHIR resources, each segment generally maps to one FHIR resource. The table below lists the most common mappings; for a much more detailed mapping see the HL7 v2-to-FHIR Implementation Guide.

HL7 v2 segment	FHIR resource	Notes
MSH (Message Header)	`MessageHeader`	Drives the event name on a `message`-type Bundle (`MessageHeader.event`).
EVN (Event Type)	`MessageHeader.event`	Folded into the MessageHeader rather than a standalone resource.
PID (Patient Identification)	`Patient`	Field-level breakdown in the next section.
PD1 (Patient Additional Demographic)	`Patient.extension`	US Core uses extensions for the additional demographic flags.
NK1 (Next of Kin)	`RelatedPerson`	One RelatedPerson per NK1 repetition.
PV1 / PV2 (Patient Visit)	`Encounter`	PV2 supplements PV1 with admit/discharge reasons and accommodation.
DG1 (Diagnosis)	`Condition`	One Condition per DG1 repetition, linked to the Encounter.
AL1 / IAM (Allergy)	`AllergyIntolerance`
OBR (Observation Request)	`ServiceRequest` and/or `DiagnosticReport`	OBR drives both, depending on context (order vs. result).
OBX (Observation/Result)	`Observation`	OBX-3 maps to `code`, OBX-5 to the value[x] of the matching FHIR datatype.
ORC (Common Order)	`ServiceRequest`
ROL (Role)	`PractitionerRole`
IN1 / IN2 (Insurance)	`Coverage`
GT1 (Guarantor)	`RelatedPerson` + `Account`	Guarantor identity is a RelatedPerson; the guarantor relationship attaches to the Account that carries the visit.

HL7 v2 PID → FHIR Patient field mapping¶

The PID segment carries patient demographics. The table below maps the most commonly used PID fields to the corresponding FHIR R4 Patient elements. Always verify against your server's CapabilityStatement and any implementation guides it conforms to (US Core, IPS, …) since profiles can require specific extensions or value sets.

HL7 v2 field	FHIR R4 element	Notes
PID-3 (Patient Identifier List)	`Patient.identifier`	Often produces multiple `identifier` entries (MRN, account number, etc.). Set `identifier.system` per assigning authority.
PID-5.1 (Family Name)	`Patient.name.family`	Within the same `Patient.name` entry as the given names.
PID-5.2 (Given Name)	`Patient.name.given[0]`	First-position given name.
PID-5.3 (Middle Name)	`Patient.name.given[1]`	Additional given name in the same array.
PID-5.4 (Suffix)	`Patient.name.suffix`
PID-5.5 (Prefix)	`Patient.name.prefix`
PID-5.7 (Name Type Code)	`Patient.name.use`	Map HL7 values (L, M, N, A, …) to FHIR `NameUse` (official, maiden, nickname, anonymous, …).
PID-7 (Date/Time of Birth)	`Patient.birthDate`	FHIR expects `YYYY`, `YYYY-MM`, or `YYYY-MM-DD`. Strip the HL7 time component if present.
PID-8 (Administrative Sex)	`Patient.gender`	Map HL7 codes (M, F, O, U, A, N) to FHIR `AdministrativeGender` (male, female, other, unknown).
PID-11 (Patient Address)	`Patient.address`	One `address` per PID-11 repetition.
PID-11.1 (Street)	`Patient.address.line`	An array. Additional address lines belong here too.
PID-11.3 (City)	`Patient.address.city`
PID-11.4 (State or Province)	`Patient.address.state`
PID-11.5 (ZIP / Postal Code)	`Patient.address.postalCode`
PID-11.6 (Country)	`Patient.address.country`
PID-11.7 (Address Type)	`Patient.address.use`	Map HL7 codes (H, B, M, O, …) to FHIR `AddressUse`.
PID-13 (Home Phone)	`Patient.telecom` with `use=home`	One `telecom` per PID-13 repetition.
PID-14 (Business Phone)	`Patient.telecom` with `use=work`
PID-15 (Primary Language)	`Patient.communication.language`
PID-16 (Marital Status)	`Patient.maritalStatus`
PID-19 (SSN)	`Patient.identifier` with the SSN system	Add a separate `identifier` entry with `system="http://hl7.org/fhir/sid/us-ssn"`.
PID-29 (Date/Time of Death)	`Patient.deceasedDateTime`	Present implies the patient is deceased.
PID-30 (Patient Death Indicator)	`Patient.deceasedBoolean`	Use only when PID-29 is not available.