What Is an HL7 Interface? How It Works, Types and How One Is Built

An HL7 interface is a live, one-directional feed that moves one kind of HL7 v2 message, such as admissions or lab results, from one healthcare system to another, usually over a TCP connection using a protocol called MLLP. Each interface has a trigger event, a sender, an interface engine that validates and maps the message, a receiver, and an acknowledgement that confirms the message arrived.

This guide is for product and engineering leads at health tech companies who have just been told "we will need an HL7 interface" by a hospital customer. It explains what an HL7 interface is made of, what the messages look like on the wire, the common interface types, what goes into an interface specification, how one is built and tested, what it costs, and the failures that show up after go-live. If you already know you need one built, our HL7 integration services team scopes and delivers interfaces end to end.

Key takeaways

• An HL7 interface is one feed for one message family in one direction. "We need HL7" usually means three to six interfaces, not one.
• Most interfaces still use HL7 v2 over MLLP, a thin TCP framing with a start byte and two end bytes. Every message gets an ACK back.
• The build is rarely the slow part. Network access, the mapping specification and the hospital's test calendar decide the date.
• Our planning range for a single low-volume inbound ADT interface on Mirth Connect is $3K to $5K; a bidirectional ORU with corrections is $12K to $25K.
• Most production failures come from local codes, Z-segments, corrected results, duplicates and feeds that stop without an error.

What is an HL7 interface?

An HL7 interface is the agreed, tested connection that carries a specific set of HL7 messages between two systems, for example ADT messages from a hospital's registration system to your application. It is defined by what triggers a message, which message types and fields it carries, how it is transported, and how each message is acknowledged.

HL7 itself is the standard. HL7 Version 2, published by HL7 International, defines pipe-delimited messages for events such as an admission, an order or a result. An interface is one working use of that standard between two named systems. That is why a hospital's interface team talks about "the ADT interface to the bed board" or "the lab results interface from the LIS" rather than "our HL7".

If you need the broader background on the standard and its versions, start with our guide to what HL7 is. This page stays on the interface: the thing you actually build, test and support.

What are the parts of an HL7 interface?

Every HL7 interface has the same eight parts: a trigger event, a sending system, a transport (usually MLLP over TCP), an interface engine, a mapping specification, an acknowledgement, an error queue and a receiving system. Missing any one of them is how interfaces fail quietly.

How does an HL7 interface send a message?

The sender opens a TCP connection, wraps each HL7 message in MLLP framing, and waits for an ACK before sending the next one. MLLP adds a single start byte and two end bytes around the message, so the receiver knows exactly where each message begins and ends on a continuous stream.

The framing is simple and worth knowing precisely, because most "the interface is connected but nothing arrives" problems sit here:

• Start block: the vertical tab character, hex 0x0B.
• Message: the HL7 segments, each ended by a carriage return, hex 0x0D.
• End block: the file separator character, hex 0x1C, followed by a carriage return, hex 0x0D.

The receiver reads until it sees 0x1C 0x0D, processes the message, and returns an ACK in the same framing. The ACK's MSA segment carries the result:

• AA (application accept): the message was received and accepted.
• AE (application error): the message was received but could not be processed, for example a required field is missing. The sender may need to correct and resend.
• AR (application reject): the message was rejected, for example an unsupported message type or version. Resending the same message will fail again.

HL7 v2 also defines an enhanced acknowledgement mode with commit-level codes (CA, CE, CR). Most hospital interfaces use the original mode above. Agree which one your interface uses in the specification.

What does an HL7 message look like?

An HL7 v2 message is plain text: one segment per line, fields separated by the pipe character, components by the caret. The first segment is always MSH, the message header, which says who sent it, what type it is and which HL7 version it follows.

Below is a synthetic ADT^A01 (admit) message and its acknowledgement. All names, identifiers and dates are invented.

MSH|^~\&|REGADT|GENHOSP|IFENGINE|PRODAPP|20260914083015||ADT^A01^ADT_A01|MSG00001|P|2.5.1
EVN|A01|20260914083000
PID|1||MRN12345^^^GENHOSP^MR||DOE^JANE^A||19800101|F|||123 MAIN ST^^SPRINGFIELD^IL^62701||(217)555-0100
PV1|1|I|4W^401^A^GENHOSP||||1234^SMITH^JOHN^^^^MD||||MED||||1|||1234^SMITH^JOHN^^^^MD|IN

MSH|^~\&|PRODAPP|IFENGINE|REGADT|GENHOSP|20260914083016||ACK^A01^ACK|ACK00001|P|2.5.1
MSA|AA|MSG00001

Notice that the ACK echoes the original message control ID (MSH-10, MSG00001) in MSA-2. That is how the sender matches each ACK to the message it sent.

Here is a shortened synthetic ORU^R01 (lab result) carrying one glucose result:

MSH|^~\&|LIS|GENHOSP|IFENGINE|PRODAPP|20260914101500||ORU^R01^ORU_R01|MSG00417|P|2.5.1
PID|1||MRN12345^^^GENHOSP^MR||DOE^JANE^A||19800101|F
OBR|1|ORD5501|LAB7781|2345-7^Glucose^LN|||20260914093000|||||||||1234^SMITH^JOHN||||||20260914101200|||F
OBX|1|NM|2345-7^Glucose [Mass/volume] in Serum or Plasma^LN||98|mg/dL|70-99|N|||F

What is the difference between an inbound and an outbound HL7 interface?

An inbound interface brings messages into your system from the hospital; an outbound interface sends messages from your system to the hospital. The direction is always described from your side, and a two-way exchange is really two interfaces with two specifications.

What are the common types of HL7 interface?

HL7 interfaces are usually named by the message family they carry. Most products that connect to hospitals need two to four of the types below, with ADT almost always first because every other feed depends on knowing who the patient is.

Two of these deserve their own deep dives: building a real-time census from ADT event processing, and the order-to-result round trip in lab interfaces that map ORM and ORU.

What goes into an HL7 interface specification?

An interface specification is the document both sides sign before anyone builds: it lists the trigger events, the exact segments and fields used, every code table, the transport details and the acknowledgement rules. A good one is the difference between a two-week test cycle and a two-month one.

How is an HL7 interface different from an API, an integration engine or FHIR?

An HL7 interface is a message feed pushed when events happen; an API is a request your system makes when it needs data. An integration engine is the software that runs interfaces, and HL7 FHIR is the newer standard used mostly for APIs. Most hospital connections today use both an HL7 v2 feed and a FHIR API.

Choosing the engine is its own decision. Our HL7 integration guide compares engines and integration patterns, and our Mirth Connect HL7 interface engine guide covers running one in production. If you want your product to consume HL7 feeds as a modern API, see how teams are turning HL7 v2 streams into FHIR APIs.

How do you build an HL7 interface, step by step?

Building one HL7 interface runs through eight steps: scoping, specification, connectivity, build, unit and failure-path testing, customer validation, cutover and monitoring. The engineering steps are predictable; connectivity and customer validation depend on the hospital's calendar.

1. Scoping. Name the workflow, the message types, the direction and the volumes. Decide what you will ignore.
2. Specification. Get sample messages from the site, not from the textbook, and write the field and code map. Collect every local code table early.
3. Connectivity. Agree the network path: a site-to-site VPN or private link, IP allowlists on both sides, the MLLP port and who initiates the connection. Hospital network teams often have the longest queue in the project.
4. Build. Configure the channel in the interface engine: listener, validation, filters, transformer, destination, ACK behaviour and error queue.
5. Unit and failure-path testing. Test every message type with the site's samples, then the failure paths: missing required fields, unknown codes, duplicates, out-of-order messages, corrections and a dropped connection.
6. Customer validation. The hospital sends test messages from its test environment and checks the results in your system, or files your messages in theirs.
7. Cutover. Switch to production endpoints, often running in parallel with the old process for a period, and watch the first days closely.
8. Monitoring. Alert on queue growth, rejected messages and, most important, on silence: no messages for longer than normal.

For a program of several interfaces, the phase durations in our HL7 integration implementation playbook are a realistic starting point: about 4 weeks of discovery, 6 to 8 weeks of build, 3 to 4 weeks of testing and 2 weeks of go-live with a parallel run. Connectivity and the hospital's validation slot move those dates more than the engineering does.

When the hospital runs Epic, its side of the interface is built in Epic Bridges by the hospital's Epic team. Epic lists the HL7 v2 interfaces it supports on open.epic, and our Epic Bridges guide explains that side. Our guide on how to integrate with Epic shows where an HL7 interface fits next to Epic's FHIR APIs and SMART apps.

How much does an HL7 interface cost?

A single HL7 interface built on Mirth Connect typically costs $3K to $25K in our planning ranges, depending on the message type, direction and volume. A one-way inbound ADT feed sits at the low end; a bidirectional results interface that handles corrections sits at the high end.

"Small" means under 1,000 messages a day, one source and one destination, and standard mappings; "large" means over 50,000 messages a day and multiple endpoints. These are the planning ranges from our Mirth Connect interface cost matrix, which also covers X12, FHIR and DICOM interfaces and the scoring rubric behind the bands.

Two costs catch teams out. A site-to-site VPN with each partner organisation typically adds $2K to $5K per partner. And an interface keeps costing money after go-live: an interface that costs $10K to build typically needs another $3K to $5K a year to keep running, for monitoring, upgrades and changes on either side.

Why do HL7 interfaces fail after go-live?

HL7 interfaces rarely fail on the happy path. They fail on the variations the sample messages did not show: site-specific segments, local codes, corrected results, duplicate messages and feeds that stop without raising an error.

• Z-segments. Custom segments whose names start with Z carry site-specific data. Each hospital's are different, and ignoring one can mean ignoring the field your workflow depends on.
• Local codes. Many sites send their own test and result codes instead of LOINC in OBX-3. Until those are mapped, you can store the data but not act on it: no alerting, no trending.
• Corrected results. A result can be sent again with a corrected status after it was final. If your interface overwrites or ignores corrections incorrectly, a clinician can act on a wrong value.
• Duplicates and order. Senders resend when an ACK is late, and messages can arrive out of order after an outage. Idempotent processing on the message control ID and event time is the fix.
• Patient merges. A merge event such as ADT^A40 changes which identifier is the survivor. Missing it splits one patient's history across two records.
• Silent stoppage. The connection stays open but no messages arrive, because a channel was stopped or a firewall rule changed. Nobody notices until a user asks why the data is old. Alert on silence, not only on errors.
• Test flag in production. A message with MSH-11 set to T reaching production, or the reverse, is a common cutover mistake.

HL7 interface readiness checklist

Before you commit a go-live date for an HL7 interface, you should be able to tick all ten items below. Each one that is still open is a likely source of delay.

Who builds and supports HL7 interfaces?

HL7 interfaces are built either by the hospital's interface team, by the vendor's own engineers, or by a specialist integration team working for the vendor. Most vendors that connect to many hospitals end up with one shared interface layer and a small team that owns it.

Our team has built 350+ interfaces on Mirth Connect, and we publish our working patterns in the open-source Mirth Connect cookbook. We build to HIPAA requirements, sign BAAs and are ISO 27001:2022 certified. When an interface also needs a FHIR API or X12 claims alongside it, the same team covers the whole connection layer, and our HL7 v2 to FHIR migration guide explains when to convert feeds into FHIR resources.

Need an HL7 interface scoped or built? Tell us the hospital systems, the message types and your target date through our HL7 integration services page, or talk to our team. For the wider picture of how we connect systems, see our healthcare interoperability solutions.

Frequently asked questions

What is an HL7 interface in simple terms?

It is a live feed that sends one kind of healthcare message, such as admissions or lab results, from one system to another as events happen. The sender wraps each message, sends it over a network connection and waits for an acknowledgement before sending the next one.

What is the difference between HL7 and an HL7 interface?

HL7 is the standard that defines the message format. An HL7 interface is one working connection that uses the standard between two named systems, with an agreed scope, field map, transport and acknowledgement rules.

Is an HL7 interface the same as an API?

No. An HL7 v2 interface pushes messages to you when events happen, while an API answers requests your system makes when it needs data. Many products use both: an HL7 feed for real-time events and a FHIR API for on-demand reads.

What is MLLP in HL7?

MLLP, the Minimal Lower Layer Protocol, is the framing HL7 v2 uses over TCP. Each message starts with the byte 0x0B and ends with 0x1C followed by 0x0D, so the receiver knows where each message begins and ends.

What does AA, AE and AR mean in an HL7 ACK?

They are the values of MSA-1 in the acknowledgement. AA means the message was accepted, AE means it was received but could not be processed, and AR means it was rejected, for example because the message type is not supported.

How long does it take to build an HL7 interface?

The engineering for a standard interface is often a matter of weeks, but the date is usually set by network access and the hospital's test calendar. For a program of several interfaces, plan roughly 4 weeks of discovery, 6 to 8 weeks of build, 3 to 4 weeks of testing and 2 weeks of go-live.

How much does an HL7 interface cost?

In our planning ranges for Mirth Connect, a small one-way inbound ADT interface is $3K to $5K and a bidirectional results interface with corrections is $12K to $25K. Add $2K to $5K per partner for a VPN and roughly $3K to $5K a year to run a $10K interface.

Do I need an interface engine to run an HL7 interface?

Not strictly, but almost every production interface uses one. An engine such as Mirth Connect handles the listener, validation, mapping, acknowledgements, retries, error queues and monitoring, which you would otherwise have to build and support yourself.

Glossary

• HL7 v2: the pipe-delimited messaging standard from HL7 International used by most hospital interfaces today.
• Interface: one agreed, tested feed of specific message types between two systems in one direction.
• MLLP: Minimal Lower Layer Protocol, the TCP framing that wraps each HL7 message with a start byte (0x0B) and end bytes (0x1C 0x0D).
• ACK / NAK: the acknowledgement message returned for each message. MSA-1 carries AA (accept), AE (error) or AR (reject).
• Segment: one line of an HL7 message, identified by a three-letter code such as MSH, PID or OBX.
• Trigger event: the event code that caused a message, such as A01 (admit) within an ADT message.
• Z-segment: a site-specific custom segment whose name starts with Z.
• Interface engine: middleware that receives, validates, maps, routes and monitors messages, such as Mirth Connect or Epic Bridges.
• Interface specification: the signed document that defines the scope, fields, codes, transport and acknowledgement rules of an interface.
• LOINC: the standard code system for lab tests and clinical observations, often mapped from local codes in OBX-3.