HL7 Integration: The Complete Guide (2026)

If your software needs to exchange clinical data with a hospital, lab, or EHR in the United States, HL7 is not optional. Every major EHR — Epic, Cerner, Meditech, Allscripts, athenahealth, eClinicalWorks — ships with HL7 v2 interfaces as the primary integration mechanism, with FHIR R4 APIs layered on top for newer workflows. Understanding HL7 is the difference between a six-week integration project and a six-month one.

This pillar guide walks through HL7 end-to-end. It is written for engineers who need to implement interfaces, IT managers who need to scope projects, and technical founders who need to decide whether to build in-house or bring in specialists. For the broader integration-engine context, pair this with our Mirth Connect complete guide and the companion FHIR integration guide.

1. What Is HL7?

Health Level Seven (HL7) is both the name of a standards family and the non-profit organization that publishes it — Health Level Seven International, founded in 1987 and based in Ann Arbor, Michigan. The name refers to Layer 7 of the OSI model (the application layer), because HL7 standards define how application-level data — patient demographics, lab orders, diagnoses, allergies, medications — is exchanged between systems.

"HL7" in practice is an umbrella for several distinct standards:

• HL7 v2 — the pipe-delimited messaging standard in use since 1989, covering versions 2.1 through 2.8.
• HL7 v3 — a reimagined XML-based standard introduced in the early 2000s, now largely superseded except for specific document-oriented use cases.
• HL7 CDA (Clinical Document Architecture) — a v3 derivative used for clinical documents (discharge summaries, progress notes), most visibly as C-CDA for US Meaningful Use / Promoting Interoperability.
• HL7 FHIR (Fast Healthcare Interoperability Resources) — the modern, REST- and JSON-based standard that is becoming the default for new healthcare APIs. See our dedicated FHIR integration guide for a full treatment.

When US healthcare professionals say "HL7" without qualification, they almost always mean HL7 v2. That is what this pillar focuses on, with FHIR covered separately.

2. A Brief History: v2, v3, CDA, and FHIR

A short timeline helps explain why your production systems have a strange mix of v2 interfaces and FHIR endpoints side by side.

The practical takeaway: v2 is not going away anytime soon. More than 95% of clinical messages in US production environments still move as HL7 v2. FHIR is growing fast for new APIs, mobile apps, and patient-facing workflows, but hospitals and labs will continue to operate v2 interfaces for decades. Any serious integration engineer needs to be fluent in both.

3. Anatomy of an HL7 v2 Message

Here is a real HL7 v2.5 patient admission message (ADT^A01). Everything about HL7 v2 follows from this example.

MSH|^~\&|EPIC|HOSPITAL|LAB|QUEST|20260417103045||ADT^A01|MSG00001|P|2.5
EVN|A01|20260417103000
PID|1||123456^^^HOSPITAL^MR||DOE^JOHN^A||19720512|M|||123 MAIN ST^^AUSTIN^TX^78701||(512)555-0134|||M||ACC001||123-45-6789
PV1|1|I|ICU^101^1^HOSPITAL||||1234^SMITH^JANE^A^MD|||MED||||||||VISIT001

3.1 Segments

Each line in the message is a segment. Every segment begins with a three-character segment ID in uppercase:

• MSH — Message Header (required, always first)
• EVN — Event Type
• PID — Patient Identification
• PV1 — Patient Visit

There are more than a hundred defined segments in the HL7 v2 specification. The ones you'll encounter most often are MSH, EVN, PID, PD1, PV1, PV2, OBX, OBR, ORC, AL1, DG1, IN1, GT1, NK1, MSA, and ERR.

3.2 Fields

Within a segment, fields are separated by pipes (|). The first field of MSH is special — it contains the encoding characters themselves (^~\&). Every other segment's fields are counted starting at position 1.

For example, in the PID segment above:

• PID-1 = 1 (Set ID)
• PID-3 = 123456^^^HOSPITAL^MR (Patient ID)
• PID-5 = DOE^JOHN^A (Patient Name)
• PID-7 = 19720512 (Date of Birth, YYYYMMDD)
• PID-8 = M (Sex)

3.3 Components and Subcomponents

Fields can contain components separated by carets (^), and components can contain subcomponents separated by ampersands (&).

The patient name DOE^JOHN^A has three components: family name, given name, and middle initial. The patient address 123 MAIN ST^^AUSTIN^TX^78701 has five components for street, other designation, city, state, and ZIP.

3.4 Repetitions

Some fields can repeat, using the tilde (~) separator. For example, a patient with multiple phone numbers: (512)555-0134~(512)555-0199.

This structure — segments, fields, components, subcomponents, repetitions — is the entire language of HL7 v2. If you understand these four concepts, you can read any HL7 v2 message. For a complete segment-by-segment breakdown with every field explained, see our dedicated guide: HL7 v2 message structure explained.

4. The Major HL7 Message Types

HL7 v2 defines hundreds of message types, identified by a trigger event (e.g., A01means "Admit/Visit Notification"). In production, you will spend 95% of your time on the following families.

4.1 ADT — Admit, Discharge, Transfer

The most common message type by volume. ADT messages notify downstream systems of patient movement and demographic changes.

Key ADT events:

Full reference with message examples for every event: HL7 ADT messages complete reference.

4.2 ORM / OMx — Orders

ORM^O01 (older versions) and OMG^O19, OML^O21, OMI^O23 (v2.5+) carry orders — lab orders, radiology orders, pharmacy orders, dietary orders — from the ordering system to the fulfilling system.

4.3 ORU — Observations and Results

ORU^R01 carries unsolicited results — primarily lab results, but also radiology reports, pathology, and vital signs. This is the message type most commonly used by reference labs sending results to ordering clinics. Full workflow walk-through: HL7 ORM + ORU lab orders and results workflow.

4.4 SIU — Scheduling

SIU^S12 through SIU^S26 notify systems of scheduling events — appointment creation, modification, cancellation, reschedule. Used heavily between EHR scheduling modules and radiology, referrals, and patient portals. See: HL7 SIU scheduling messages explained.

4.5 MDM — Medical Document Management

MDM^T02 and MDM^T08 move clinical documents — consult notes, discharge summaries, pathology reports — between systems. Often paired with CDA documents embedded in an OBX segment. See: HL7 MDM document messages.

4.6 DFT — Detail Financial Transaction

DFT^P03 and DFT^P11 carry charges and financial detail — patient billing transactions from the charging system to the billing system. See: HL7 DFT billing messages.

4.7 RDE / RDS — Pharmacy Orders

RDE^O11 (encoded pharmacy order) and RDS^O13 (pharmacy dispense) handle medication orders and dispensing events between CPOE, pharmacy systems, and MAR.

4.8 VXU — Vaccination Records

VXU^V04 submits immunization records to state Immunization Information Systems (IIS), a federally mandated workflow for all US immunization providers. See: HL7 VXU immunization messages.

4.9 ACK — Acknowledgment

Every production HL7 message is acknowledged by an ACK (or occasionally a message-type-specific acknowledgment). Getting ACK handling right is where most integrations fail in subtle ways — see section 7 and our deep dive on HL7 ACK/NAK explained.

5. Delimiters, Encoding, and Data Types

HL7 v2 is famously quirky about encoding. A few things to know:

5.1 Encoding characters

Declared in MSH-1 and MSH-2:

• Field separator: | (pipe)
• Component separator: ^ (caret)
• Repetition separator: ~ (tilde)
• Escape character: \ (backslash)
• Subcomponent separator: & (ampersand)

You can technically change these characters, but do not. Every production system assumes the defaults.

5.2 Escape sequences

When a pipe or caret appears inside data (e.g., in a free-text comment), it is escaped:

5.3 Character encoding

MSH-18 declares the character set. In the US, this is almost always ASCII, 8859/1 (Latin-1), or increasingly UTF-8. Encoding mismatches are a common silent cause of name and address corruption — if you ever see Señora becoming Se?ora somewhere downstream, you have a character-set problem.

5.4 Date/time formats

HL7 uses YYYYMMDDHHMMSS[.SSSS][+/-ZZZZ] — for example 20260417103045-0500 for 10:30:45 on April 17, 2026, in Central Time. Not ISO-8601. Every transformer writing to a JSON/FHIR system needs to convert.

5.5 Data types

HL7 v2 defines dozens of data types — ST (string), NM (numeric), DT (date), TS (timestamp), XPN (extended person name), XAD (extended address), CE (coded element), XCN (extended composite name/ID), and many more. The HL7 standard documents spell out which data type is used for every field of every segment.

6. How HL7 Messages Move: MLLP, Files, and APIs

A message format is useless without a way to move it. HL7 v2 doesn't define a transport — but three transports dominate production environments.

6.1 MLLP (Minimum Lower Layer Protocol)

MLLP over TCP is the overwhelmingly dominant transport in US hospitals. It is a simple framing protocol: every message is wrapped in <VT> (0x0B) at the start and <FS><CR> (0x1C 0x0D) at the end, sent over a long-lived TCP socket.

MLLP can run:

• Clear-text on an internal network (common in legacy deployments; increasingly unacceptable for HIPAA).
• MLLP over TLS (MLLPS) — the modern default.
• MLLP over VPN — when two organizations need to exchange data across the public internet.

MLLP is reliable, low-latency, and trivially simple. It is also unforgiving — firewall rules, TLS cipher mismatches, and EOF framing bugs cause most production outages. Deep dive: MLLP protocol explained.

6.2 File-based exchange

Second-most-common transport: HL7 messages written to files and transferred via SFTP, FTPS, or shared network drives. Typical for batch-oriented workflows — end-of-day lab uploads, payer enrollment files, overnight reconciliation runs.

6.3 Web services (SOAP and REST)

Older EHR integrations sometimes wrap HL7 v2 messages in SOAP envelopes. Modern deployments increasingly use HTTP POST with HL7 v2 in the body. FHIR-based workflows replace HL7 v2 entirely with REST JSON.

6.4 Queues (JMS, Kafka, RabbitMQ)

Large-scale deployments often use enterprise message queues as a resilience layer — the HL7 arrives via MLLP, is immediately pushed onto a durable queue, and downstream consumers process from the queue. This pattern is becoming common in cloud-native integration architectures.

7. Acknowledgments: ACK, NAK, and Error Handling

Every HL7 v2 message must be acknowledged. Getting ACK handling wrong is the single most common production bug.

7.1 ACK modes

Declared in MSH-15 (accept) and MSH-16 (application) on the outbound message:

• AL — Always acknowledge
• NE — Never acknowledge
• ER — Acknowledge only on error
• SU — Acknowledge only on success

7.2 ACK codes

The acknowledging system returns an ACK message with MSA-1 set to one of:

• AA — Application Accept (success)
• AE — Application Error (message was syntactically valid but failed application rules)
• AR — Application Reject (message rejected — sender should not retry without changes)
• CA — Commit Accept (HL7 v2.4+)
• CE — Commit Error
• CR — Commit Reject

7.3 Why this matters

A sender that doesn't wait for ACKs will lose messages on network blips without knowing it. A receiver that sends AA before actually persisting the message will claim success on data it then drops. Both patterns are shockingly common.

The correct behavior: only ACK AA after the message is durably persisted and all mandatory processing has completed. For the full ACK/NAK playbook with retry patterns and edge cases, see: HL7 ACK/NAK explained.

8. Reference Architectures for HL7 Integration

Three architectures cover almost every production deployment.

8.1 Point-to-point

The simplest pattern: System A connects directly to System B via MLLP. Works for a single interface. Breaks down fast — with N systems you end up with N × (N-1) connections to maintain.

8.2 Hub and spoke (integration engine)

One central integration engine (most commonly Mirth Connect, Rhapsody, or InterSystems) receives every message and routes it to the correct destinations. Every system connects to the engine once. This is the default pattern for hospitals and the one we recommend for virtually all mid-to-large deployments.

8.3 Message-bus / event-driven

Cloud-native variant of hub-and-spoke. Messages land on a durable queue (Kafka, SQS, Azure Service Bus) and are consumed by microservices. Typical in modern healthtech architectures where HL7 is one input alongside FHIR APIs, mobile events, and IoT data.

9. Common HL7 Use Cases

The patterns we see most in client engagements:

1. EHR → Lab: ORM orders out, ORU results back.
2. EHR → Radiology: ORM or OMG orders out, ORU reports back, DICOM separately.
3. EHR → Pharmacy: RDE orders out, RDS dispenses back.
4. EHR → Billing: DFT charges, ADT discharges.
5. EHR → Scheduling: SIU appointment notifications.
6. EHR → Immunization registry: VXU submissions to state IIS.
7. EHR → Analytics: ADT and ORU feeds into data warehouses.
8. Ancillary → EHR (document push): MDM transactions.
9. EHR → EHR (patient transfer): full ADT + document feed.
10. Cross-vendor integration: EHR ↔ CRM, EHR ↔ patient engagement platform, EHR ↔ RCM vendor.

For specific vendor integrations, see our dedicated pages: Epic EHR integration and Cerner EHR integration.

10. HL7 v2 vs HL7 v3 vs FHIR: Choosing the Right Standard

A fair, honest comparison of your three realistic options.

Practical rule of thumb:

• For inter-system messaging inside a hospital ecosystem — use v2. Every EHR ships with it; every integration engine speaks it natively.
• For clinical documents (discharge summaries, CCDs for HIEs) — use C-CDA.
• For modern APIs, mobile apps, patient-facing workflows, and anything net-new in 2026 — use FHIR R4.
• Do not use HL7 v3 messaging for new work. It exists but is essentially legacy.

For a deeper comparison with migration guidance, see HL7 v2 vs v3 vs FHIR and our expanded treatment in the FHIR integration guide.

11. Implementation Challenges and How to Avoid Them

HL7 integrations look straightforward in the spec and are rarely straightforward in production. The issues we see repeatedly:

11.1 Vendor-specific deviations

Every EHR vendor bends the HL7 spec. Epic's ADT is not Cerner's ADT. Custom Z-segments (vendor-specific extensions beginning with Z) are everywhere. Assume every interface needs vendor-specific mapping.

11.2 Version mismatches

A sending system on v2.3 and a receiver on v2.5.1 will disagree on field lengths, code sets, and segment rules. Agree on a common version per interface and document it.

11.3 Character encoding

Latin-1 vs UTF-8 mismatches silently corrupt names, addresses, and free-text notes. Always declare encoding in MSH-18 and validate end-to-end.

11.4 Date/time and time zones

HL7 time zones are optional and often omitted. Assume every timestamp from a sender is in the sender's local time unless it explicitly says otherwise. This single assumption prevents an entire category of bugs.

11.5 Code set normalization

LOINC for lab tests, SNOMED CT for clinical terms, RxNorm for medications, ICD-10 for diagnoses, CPT for procedures — different systems use different code sets for the same concept. Mapping is where most engineering effort actually goes.

11.6 Error handling and retries

Messages will fail. Networks will drop. Receivers will restart. Every production channel needs idempotent processing, durable queueing, dead-letter handling, and operator visibility.

11.7 Performance at scale

A hospital's ADT feed can push 50,000 messages per day; a national lab's ORU feed can push 10 million. Synchronous transformer logic, unindexed database lookups, and naïve logging will all become bottlenecks. Covered in detail for Mirth deployments in Mirth Connect performance tuning.

11.8 Security and PHI handling

Every HL7 v2 message contains PHI. TLS is non-negotiable. Logging entire messages to disk without redaction is a HIPAA incident waiting to happen.

A full running list of the errors we've seen across hundreds of deployments: common HL7 integration errors and fixes.

12. Testing, Validation, and Certification

Good HL7 testing has three layers.

12.1 Syntactic validation

Does the message parse? Are segments in the right order? Are required fields present? Tools: HL7 Inspector, HAPI's validator, Mirth Connect's built-in HL7 parser.

12.2 Semantic / conformance validation

Does PID-3.4 contain the expected assigning authority? Does the sex code match the allowed values from Table 0001? This is where vendor-specific rules apply.

12.3 Workflow / integration testing

Does sending an ADT^A01 actually create a patient in the downstream system? Does an A03 close the account? Does an A40 merge correctly without orphaning data? This layer requires real end-to-end test environments.

Tools we recommend: sample messages and testing tools walkthrough.

12.4 Certification

Some HL7 interfaces require formal certification — for example IIS submissions (CDC WSDL and message specs), ELR reporting to state health departments, and cancer registry submissions. Each has its own test harness and submission process.

13. HL7 Integration Timelines and Cost

A realistic view of what an HL7 integration actually takes.

Actual numbers vary with vendor complexity, custom transformations, compliance requirements, and team experience. Our HL7 integration services for the USA page has more detail on scope and fixed-bid options.

14. When to Bring in HL7 Expert Support

You need outside help when any of the following is true:

• Your timeline is fixed (EHR go-live, customer contract) and you do not have at least one engineer who has shipped an HL7 interface before.
• A production interface is failing and no one on your team understands why.
• You need 24/7 coverage because clinical workflows depend on the feed.
• You're integrating with a vendor you haven't worked with (Epic, Cerner, athenahealth, Meditech, Allscripts) and need someone who has.
• Your CIO or client has asked for HIPAA, HITRUST, or SOC 2 documentation of your integration layer.
• You're migrating from legacy interfaces to a new integration engine or cloud platform.

Our Mirth helpdesk offers under-15-minute SLA for emergency HL7 issues, and our broader services team covers everything from greenfield builds to managed HL7 operations. Every engagement is covered by NDA and staffed by engineers with 12+ years of HL7 v2 and FHIR experience. For specific technology choices, our Mirth Connect complete guide covers the integration engine we most commonly recommend.

15. Frequently Asked Questions

Related Reading

• Mirth Connect: The Complete Guide
• FHIR R4 Integration: The Complete Guide
• HL7 Integration Services — USA
• What Is Mirth Connect — Guide for Healthcare Teams
• Mirth Connect + FHIR: Powering the Next Generation of Healthcare Data Exchange
• Epic EHR Integration Services
• Cerner EHR Integration Services