HL7 and FHIR Integration: A Complete Guide

What is HL7 FHIR integration?

A patient’s story is never held in one system. Registration happens in the hospital EHR, a blood test is resulted in the laboratory system, the prescription is filled in a pharmacy system, the claim is adjudicated by a payer, and the follow-up reminder comes from a patient app. Each was built by a different vendor, at a different time, with its own idea of what a patient, a visit or a result looks like. HL7 and FHIR integration is the discipline of making them agree, reliably, at volume, and without anyone re-keying data.

Health Level Seven International has defined how healthcare systems exchange information since 1987. Its version 2 messaging standard is the most widely deployed interface format in hospitals. Its newest standard, FHIR, does the same job with the architecture of the modern web: resources instead of messages, REST instead of point-to-point sockets, JSON instead of pipe-delimited text. A working healthcare organization in 2026 almost always runs both, so the practical skill is not choosing between HL7 and FHIR but making them work together.

Exchanging data versus using it

Interoperability is the ability of two systems to exchange information and to use what was exchanged. Moving a file from a lab to a hospital is easy. Making sure the hospital’s software knows that the third value is a serum glucose in mg/dL, belongs to this patient and not her mother, and replaces yesterday’s preliminary result is the hard part.

Healthcare exchange is harder than most enterprise integration for three reasons. Identity is uncertain, because there is no universal patient identifier. Meaning is coded in different vocabularies on each side. And the consequences are clinical: a mis-mapped unit is a patient-safety event, not a reporting error. For the policy side of the topic (HIE, TEFCA, USCDI and the Cures Act) see our healthcare interoperability guide.

What is HL7? The organization, HL7 v2 and its relatives

“HL7” means three different things, and integration conversations go wrong when they get mixed up. It is an organization, Health Level Seven International. It is a family of standards that organization publishes. And in everyday hospital use it is shorthand for one of them: HL7 version 2, the event-driven messaging standard that connects most clinical systems in the world. HL7 is not a programming language. It is a set of data formats and rules that software written in any language can read and write.

HL7 message structure: an ADT^A01 example, segment by segment

An HL7 v2 message is plain text. It is made of segments, one per line, each starting with a three-character ID. Segments hold fields separated by |, and fields can be split into components (^), repetitions (~) and sub-components (&), with \ as the escape character. The delimiters are declared in the first segment, so a parser never has to guess. Fields are identified by position: PID-5 is the fifth field of the PID segment, and the standard defines what each position means.

Here is a complete admit message for a fictitious patient. Pick a segment to see what it carries, or hover any value to see its field number.

MSH|^~\&|HIS|CITYHOSP|LIS|CITYLAB|20260916083000||ADT^A01^ADT_A01|MSG00001|P|2.5.1EVN|A01|20260916082500PID|1||MRN-0045821^^^CITYHOSP^MR||ROY^AMARA^K||19840312|F|||14 HARBOUR ST^^SEATTLE^WA^98101||^PRN^PH^^^206^5550142PV1|1|I|4W^412^A^CITYHOSP||||1122^PATEL^NEERAJ^^^DR|||MED|||||||||V2026-77812|||||||||||||||||||||||||20260916082500

HL7 message types you will meet on day one

MLLP, acknowledgements and Z-segments

Two facts about v2 rarely appear in an introduction and always appear in a project. First, the standard says little about transport. In practice messages travel over MLLP, the Minimal Lower Layer Protocol: each message is wrapped in a start byte (0x0B) and end bytes (0x1C 0x0D) on a TCP socket, and every message expects an ACK back. An interface is a persistent connection with a heartbeat, not a stateless call.

MSH|^~\&|LIS|CITYLAB|HIS|CITYHOSP|20260916083001||ACK^A01^ACK|ACK00001|P|2.5.1
MSA|AA|MSG00001

Second, the standard allows locally defined Z-segments for data it does not cover. Nearly every hospital has them, no two hospitals’ match, and they are the biggest single reason that “standard HL7” interfaces still need to be specified system by system. Our HL7 integration team starts every project with a Z-segment inventory for exactly this reason.

What is FHIR? Resources, the FHIR API and FHIR R4

FHIR, Fast Healthcare Interoperability Resources (pronounced “fire”), is HL7’s standard for exchanging healthcare data using the architecture of the web. The first draft appeared in 2014. Release 4 (R4), published in December 2018, became the version most regulations and platforms build on; R4B followed in 2022 and R5 in March 2023, and R6 is in development as the first release intended to be largely normative. FHIR was designed by people who had implemented v2 and v3 for years and wanted something a web developer could pick up in an afternoon, without losing clinical depth.

The unit of FHIR is the resource: a small, well-defined object for one concept, such as a Patient, Encounter, Observation or MedicationRequest. A resource has typed elements with defined cardinality, a human-readable narrative, and an identity: a URL where it can be read, updated or deleted. Resources point to each other by reference, so an Observation names the Patient it was measured on, just as a web page links to another. Here is the same fictitious patient from the ADT message, as a FHIR R4 Patient resource:

{
  "resourceType": "Patient",
  "id": "pat-0045821",
  "identifier": [{
    "type": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "MR" }] },
    "system": "https://cityhospital.example.org/identifiers/mrn",
    "value": "MRN-0045821"
  }],
  "name": [{ "use": "official", "family": "Roy", "given": ["Amara", "K"] }],
  "gender": "female",
  "birthDate": "1984-03-12",
  "address": [{ "line": ["14 Harbour St"], "city": "Seattle", "state": "WA", "postalCode": "98101" }],
  "telecom": [{ "system": "phone", "value": "206-555-0142", "use": "home" }]
}

The FHIR API: four operations do most of the work

FHIR resources are exchanged through a RESTful FHIR API over HTTPS: GET to read or search, POST to create, PUT to update, DELETE to remove, with standard status codes and JSON or XML bodies. This is the change that matters most for a development team: an integration becomes an API client, testable with the same tools as any other web service.

// read one resource by its id
GET  [base]/Patient/pat-0045821

// search: find the patient by MRN, then her glucose results, newest first
GET  [base]/Patient?identifier=https://cityhospital.example.org/identifiers/mrn|MRN-0045821
GET  [base]/Observation?patient=pat-0045821&code=http://loinc.org|2345-7&_sort=-date&_count=20

// create and update: the body is the resource; the response carries id and version
POST [base]/Observation            Content-Type: application/fhir+json
PUT  [base]/Patient/pat-0045821    If-Match: W/"3"

A search returns a Bundle, a resource that contains other resources, with paging links. Bundles also come as transaction (all or nothing), batch, document and message. The If-Match header carries the resource version, so two systems cannot silently overwrite each other.

Profiles, extensions and implementation guides

1. Profile

   A constraint on a base resource: which elements are required, which value sets apply, what cardinality. Base Patient permits almost anything; US Core Patient makes name, gender and an identifier mandatory. A server lists its profiles in its CapabilityStatement.

2. Extension

   A defined way to carry data the base resource has no element for. It is the FHIR answer to the Z-segment, but with a published definition at a URL, a data type and a place in the model.

3. Implementation guide

   A package of profiles, extensions, value sets and search rules for a use case: US Core for certified EHR APIs, the International Patient Summary, Da Vinci for payers, SMART App Launch, Bulk Data. Conformance is stated against an IG, not against “FHIR”.

4. Terminology resources

   CodeSystem, ValueSet and ConceptMap are resources too, so vocabularies and the maps between them can be fetched and validated over the same API. That is what makes semantic interoperability machine-checkable.

HL7 vs FHIR: the key differences

Every architecture review eventually draws this table. It is worth drawing carefully, because the right conclusion is not “replace v2 with FHIR”. The two standards solve the same problem with the tools of their eras, and the differences that matter are about who consumes the data and how.

How HL7 and FHIR integration works in practice

This is how most real HL7 and FHIR integration is done today. The EHR and departmental systems keep emitting the v2 messages they always have. An integration layer receives them, translates each into FHIR resources, and exposes those through a FHIR API. Modern apps never see a pipe-delimited message, and legacy systems never see JSON. Each side keeps its own language, and translation happens once, in one place, under control.

1. SystemHospital EHR

   Registers the patient and emits events as they happen.

2. MessageHL7 v2 ADT^A01 message

   MSH · EVN · PID · PV1, pipe-delimited, sent over MLLP.

3. ProcessIntegration engine: receive, acknowledge, parse

   The listener persists the message, returns an ACK and splits it into segments and fields.

4. ProcessTransformation and mapping

   PID → Patient, PV1 → Encounter; codes translated; identifiers resolved against the master patient index.

5. ProcessValidation

   Resources checked against the target profile. Failures go to an error queue, never dropped.

6. DataFHIR resources

   Patient and Encounter created or updated on the FHIR server, versioned.

7. APIFHIR API

   GET, POST, search and Subscriptions, authorized with OAuth 2.0 and SMART on FHIR.

8. SystemModern healthcare application

   Patient app, care-coordination tool, analytics or AI service.

• System
• HL7 message
• Process
• Data · resource
• FHIR API

Seven responsibilities of the translation layer

Each one is a place an integration can fail, and each has a standard remedy.

The direction runs both ways. An app that creates a FHIR ServiceRequest, such as a booking or a referral, often has to reach a lab or scheduling system that only accepts a v2 ORM or SIU message. The same layer composes that message and waits for the ACK. A well-designed platform treats v2 and FHIR as two interfaces onto one canonical model, so adding a third format later is another adapter, not another architecture.

HL7 to FHIR mapping: PID to Patient, field by field

Mapping is where integration projects spend most of their effort and where most defects start. Below is the core of the most common map, the PID segment to the FHIR Patient resource, following HL7’s published V2-to-FHIR implementation guide. Hover or tap a row and the matching value lights up in both the HL7 message and the FHIR JSON.

PID|1||MRN-0045821^^^CITYHOSP^MR||ROY^AMARA^K||19840312|F|||14 HARBOUR ST^^SEATTLE^WA^98101||^PRN^PH^^^206^5550142

{
  "resourceType": "Patient",
  "id": "pat-0045821",
  "identifier": [{
    "type": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "MR" }] },
    "system": "https://cityhospital.example.org/identifiers/mrn",
    "value": "MRN-0045821"
  }],
  "name": [{ "use": "official", "family": "Roy", "given": ["Amara", "K"] }],
  "gender": "female",
  "birthDate": "1984-03-12",
  "address": [{ "line": ["14 Harbour St"], "city": "Seattle", "state": "WA", "postalCode": "98101" }],
  "telecom": [{ "system": "phone", "value": "206-555-0142", "use": "home" }]
}

The other core segment maps

The same discipline extends to every segment an integration touches. These are the starting points the V2-to-FHIR guide defines.

Why mapping is harder than the diagram suggests

FHIR resources explained: the dozen that carry most integration traffic

Of the roughly 145 resources in FHIR R4, about twelve carry the overwhelming majority of integration work. Each card names what the resource represents, the elements an integration touches most, and the HL7 v2 segment it is usually built from. Filter by where they sit in a clinical workflow.

Also common: Coverage and Claim for payer exchange, Immunization for registries, DocumentReference to index C-CDA and PDF documents, Appointment, Schedule and Slot for booking, Location and Device. Infrastructure resources do the plumbing: Bundle wraps sets of resources, OperationOutcome carries errors, CapabilityStatement declares what a server supports, and AuditEvent and Provenance record who did what and where data came from. For profiling and Bulk Data in production, see FHIR R4 in practice.

A reference architecture for HL7 and FHIR integration

This is a conceptual reference architecture: how the parts of HL7 and FHIR integration are commonly arranged, not one vendor’s design. Real deployments merge, split or skip tiers depending on scale and what already exists. Data flows top to bottom, from a clinical system to an application. Select a tier to see what lives there.

Expect variations. A hospital whose EHR already exposes a certified FHIR API may need an engine only for departmental v2 traffic. A payer may have no v2 at all. A cloud data platform may swap the FHIR server for a lakehouse fed by Bulk Data. The tiers are responsibilities; which products fill them is a design choice, and “which vendor” is the wrong first question. When several EHRs must be reached through one API, the pattern is our universal EHR integration layer.

Who sends what: integration across the ecosystem

Read down the last column and the architecture explains itself. Inside the hospital, between long-running systems, HL7 v2 dominates and will for years. At every boundary where a person, a partner or a modern application needs the data, FHIR is the answer. The integration layer sits exactly on that boundary, which makes it the highest-leverage component an organization owns.

EHR integration workflow: one registration, end to end

The most common integration in any hospital is the flow of patient identity from the EHR to everything else. Following one registration from the front desk to a downstream app shows where each part of the architecture earns its place, and where each failure mode would first show up.

1. 01 · EHR
   Patient registered

   A clerk registers Amara Roy, or she pre-registers in a portal. The EHR assigns or finds her MRN and opens an encounter. Nothing has left the EHR yet, but every downstream system inherits the data quality captured here.

2. 02 · ADT
   EHR raises an ADT event

   Saving fires the trigger: A04 for an outpatient registration, A01 for an inpatient admission. MSH-10 gets a unique control ID; PID and PV1 are filled from the registration.

3. 03 · MLLP
   HL7 v2 message sent

   The message is framed in MLLP and written to the engine’s socket. If the socket is down, the EHR’s outbound queue holds it, and queue depth is the first metric an operations team watches.

4. 04 · ACK
   Engine receives and acknowledges

   The listener persists the raw message to its transaction log, then returns AA. Persist, then acknowledge: an acknowledged message must never be lost. A malformed frame gets AR or AE with an error segment.

5. 05 · Check
   Message validation

   Structural checks (segments, data types, version) and business checks (known facility, valid patient class, well-formed MRN). Failures go to a reviewable queue with the raw text, and do not block the messages behind them.

6. 06 · Map
   Transformation and mapping

   PID becomes a Patient, PV1 an Encounter. The MRN is looked up in the master patient index: an existing Patient is updated, a new one created, and a possible duplicate goes to a human data steward, not an automatic merge.

7. 07 · FHIR
   FHIR resources created or updated

   A conditional update on Patient by identifier, then a create or update on Encounter that references it, validated against the deployment’s profiles. The engine records the resource IDs against the control ID, closing the trace.

8. 08 · API
   The FHIR API makes it available

   GET [base]/Encounter?patient=…&status=in-progress now works for any authorized client, and a Subscription can notify interested apps. A client sees only what its scopes and the patient’s consent allow.

9. 09 · Apps
   Downstream applications consume it

   A care-coordination tool fetches the Encounter, the patient app shows the visit, the bed board updates, and the analytics pipeline picks it up on the next Bulk Data export. None of them parsed a pipe.

10. 10 · Care
    Clinical and business use

    The ward knows the patient is coming, eligibility is checked against her coverage, and her first lab result will attach to this encounter automatically. Every step is logged, so “did the registration reach the lab, and when” is one query.

The HL7 interface engine: what it does, and why it is not just middleware

An integration engine, also called an HL7 interface engine, receives messages from source systems, transforms them and delivers them to destinations, with the queuing, error handling and logging that make the flow reliable. Hospitals commonly run Mirth Connect, Rhapsody, Cloverleaf or InterSystems HealthShare, and Epic sites use Epic Bridges. Cloud platforms offer managed building blocks too: Azure Health Data Services (a FHIR service with templates that convert HL7 v2), Google Cloud Healthcare API (HL7v2 and FHIR stores) and AWS HealthLake (a managed FHIR data store). The responsibilities are the same whichever product you pick.

The unit of work is the channel: one configured pathway from a source, through processing steps, to one or more destinations. Think of it as a single interface written down as configuration. An engine runs many at once.

source      MLLP listener :6661          # persist, then ACK (AA)
parse       ORU^R01, HL7 v2.5.1
transform   OBR -> DiagnosticReport, each OBX -> Observation
map         local test code -> LOINC, OBX-6 units -> UCUM
validate    laboratory Observation profile  # $validate
deliver     POST transaction Bundle -> FHIR server
on failure  retry with back-off, then error queue + alert

Security, HIPAA and SMART on FHIR

Neither HL7 v2 nor FHIR is a security standard, and neither makes a system compliant on its own. HL7 v2 says almost nothing about security: an MLLP interface is a plaintext TCP socket unless it is wrapped in TLS or a VPN. FHIR defines how security applies to its API but relies on established web standards: TLS for transport, OAuth 2.0 and OpenID Connect through the SMART App Launch framework for authorization and identity, and AuditEvent and Provenance for accountability.

How SMART on FHIR authorizes an app to read a record

1. The app requests access

   Either a standalone launch, or launched from inside the EHR with patient context already set.

2. Discovery

   The app reads the server’s SMART configuration to find the authorization and token endpoints.

   .well-known/smart-configuration

3. The user authorizes scopes

   OAuth 2.0 authorization code flow: the user signs in and approves the requested scopes.

   patient/Observation.rslaunch/patientopenid

4. Access token issued

   A short-lived bearer token carrying the granted scopes and patient context, plus a refresh token if offline access was granted.

5. FHIR API call with the token

   The server enforces the scopes, the patient compartment and any consent rules on every request.

   GET [base]/Observation?patient=…

6. AuditEvent recorded

   Who accessed what, when, from where and on whose behalf, kept for review.

Security controls, one by one

13 common HL7 and FHIR integration challenges, and how to handle each

Every one of these shows up in most projects. Each is listed with why it happens, because the remedy follows from the cause.

14 HL7 and FHIR integration best practices

These are practical rather than aspirational. Each is something a team can do on the next project, and each answers one or more of the failure modes above.

1. Define the data requirements firstWhich resources, elements and codes, for which consumers, at what latency. “Get everything into FHIR” never finishes; a named use case does.
2. Establish a canonical data modelTranslate every source into one internal model, in practice profiled FHIR resources. A new source then touches one adapter, not every pair.
3. Map from the published guideStart from HL7’s V2-to-FHIR guide; where your data forces a different choice, record what and why.
4. Validate at the boundaryStructural validation on receipt, profile validation before write. It turns “the data looks wrong” into fixable work items.
5. Version the APIState the FHIR and profile versions consumers can rely on. Change additively, deprecate with notice, never break a consumer.
6. Keep reviewable error queuesA failed message is a work item with an owner, a reason and a replay button, never just a log line.
7. Log every transaction end to endControl ID in, resource IDs out, every hop timestamped. “Did the result reach the ward?” is one query.
8. Use standard terminologiesLOINC, SNOMED CT, ICD-10, RxNorm and UCUM, with a terminology service and maintained maps from local codes.
9. Secure the API, not each appEnforce SMART on FHIR, scopes and audit at the server or gateway, so every consumer inherits the same controls.
10. Retry with back-off and idempotencyTransient failures should heal themselves. Conditional creates and updates stop a retried message creating a duplicate.
11. Test with real message shapesA de-identified corpus of production messages, malformed ones included, is a project’s most valuable test asset.
12. Monitor integration as a servicePer-channel volume, latency, error rate and heartbeat; alerts on silence; a status page operations can read.
13. Plan identity from day oneDecide matching, merge propagation and who resolves ambiguity before the first message flows. Retrofitting an MPI is far harder.
14. Document mappings as living artifactsA mapping spec that lives beside the code and is readable by a clinical informaticist lets the next team change it safely.

Why healthcare AI depends on HL7 and FHIR integration

Every useful clinical AI system, whether a deterioration score, a readmission model, an ambient documentation assistant or a population-health stratifier, sits downstream of the same thing: a reliable, coded, longitudinal, well-governed supply of clinical data. Interoperability is not next to the AI roadmap. It is the first item on it.

FHIR is a good substrate for machine learning because it does feature engineering that used to eat most of a data scientist’s time. An Observation has a LOINC code, a UCUM unit, a timestamp and a patient reference whichever lab produced it. Bulk Data export delivers a whole population in that shape as NDJSON, so a model built on it travels across sites in a way a model built on one hospital’s schema never did. At inference time, a model that reads live FHIR resources and writes back a risk score as an Observation, a suggested action as a Task or an alert as a Flag appears inside the clinician’s existing workflow, and CDS Hooks can call it when a chart opens or an order is signed. The AI does not need its own screen; it needs the interface.

When to use HL7, FHIR, or both

The choice is rarely open. It is dictated by what already exists, who the consumer is, and what the rules in your market require. Answer two questions for a quick steer, then check the situations below.

How Bonami can help with HL7 and FHIR integration

Everything in this guide is work our healthcare technology practice does for hospitals, health systems, payers, public health agencies and digital health companies. The guide is meant to be useful whether or not you work with us; this section says plainly what we do, so a team planning an integration knows what to ask.

From our published case studies

This is work we have delivered, not a service list. We also built APPNEA, a sleep and dental care platform with seven HL7 interfaces covering registration, demographics, claims and results.

Frequently asked questions about HL7 and FHIR integration