How HL7 Integration Works for Healthcare Apps: Messages, Engines and Go-Live
Key Takeaways
- Most hospitals still send data as HL7 v2 messages over a connection type called MLLP. Even a hospital that offers FHIR for lookups will often send admissions, lab results and schedules as HL7 feeds.
- Name the exact message types and trigger events you need (ADT^A04, ORU^R01, SIU^S12) in your first conversation with a hospital. Their interface team can’t scope “an HL7 integration” until you do.
- MLLP doesn’t encrypt anything, so each hospital connection needs a site-to-site VPN or MLLP over TLS before any patient data (PHI) can flow.
- Mirth Connect became closed-source with version 4.6 in March 2025. Your options now are to pay NextGen for a license, run a free open-source fork, or use a different engine.
- Mapping fields and testing with real sample messages take most of the time and cause most go-live delays. Writing the code that receives messages is the quick part.
Imagine a hospital agrees to send your app admissions and lab results. Instead of an API key, the interface analyst may ask about the trigger events you accept, your ACK mode, and whether a VPN tunnel can be ready by the end of the month. This is where many teams understand that HL7 integration involves its own network setup, requirements, and testing.
This guide is for product and engineering teams that need to connect an app to hospital or lab systems using HL7 v2. It walks through the message types you will need, how an HL7 interface sends data, how to pick a healthcare integration engine, and what usually goes wrong after launch. Tech Exactly’s healthcare software development team builds these interfaces for clinical and operational products, and the steps below follow the order a real project works.
If you haven’t picked a standard yet, HL7 vs FHIR is a separate topic. This article assumes the hospital has already told you, “We’ll send it as HL7.”
What Is HL7 Integration?
HL7 integration means connecting two healthcare systems so they can share data as HL7 messages. In practice that usually means HL7 version 2 (v2), a standard published by HL7 International and still used by most US hospital interfaces. An HL7 interface is one of those connections. It has a sender, a receiver, an agreed list of message types and a way to carry messages between the two.
An HL7 v2 message is plain text. Each line is called a segment and starts with a three-letter code, and the fields inside a segment are split by the pipe character (|). Here’s a shortened admission message (the patient is made up):
MSH|^~\&|EPIC|MERCYHOSP|YOURAPP|YOURAPP|20260922101500||ADT^A04|MSG00017|P|2.5.1
PID|1||448812^^^MRN||DOE^JANE||19710314|F|||12 OAK ST^^DAYTON^OH^45402
PV1|1|O|CARDIO^^^MERCYHOSP||||1234^SMITH^ALAN
MSH is the header. It says what kind of message this is (ADT^A04, meaning a patient was registered). PID holds the patient’s details and PV1 holds the visit. The app needs to understand these fields correctly before it can do anything useful with the message. Each hospital may also use some of these fields in its own way.
HL7 EHR integration is one of several ways to get data out of an EHR. FHIR APIs work well when your app needs to look something up on demand, or when patients use the app directly. HL7 v2 feeds work well when the hospital needs to push events to you as they happen. Many products use both, so EHR integration for healthcare apps usually ends up as a mix of the two standards.
Which HL7 Message Types Does Your App Need?
Begin every project with a list of the message types and start events you’ll send or receive. Hospital interface teams think in these terms, and a clear list can reduce your first meeting from an hour to ten minutes drastically.
| Message type | Common trigger events | What it carries | Typical use in an app |
|---|---|---|---|
| ADT (admit, discharge, transfer) | A01 admit, A03 discharge, A04 register, A08 update, A40 merge | Patient details and visit status | Keeping your patient list up to date, starting follow-up after discharge |
| ORM / OML (orders) | ORM^O01, OML^O21 | New or changed orders for labs, imaging and other services | Sending orders from your app to a lab or radiology system |
| ORU (results) | ORU^R01 | Test results, with one OBX segment for each value | Showing lab results, feeding remote monitoring dashboards |
| SIU (scheduling) | S12 new, S13 reschedule, S14 modify, S15 cancel | Appointment details | Reminder, intake and telehealth apps that follow the hospital’s calendar |
| MDM (documents) | T02 new document with content | Clinical notes and reports | Sending a summary or report your app created back to the patient’s chart |
| DFT (financial) | P03 post charges | Charges and procedure codes | Billing and revenue cycle products |
| VXU (vaccinations) | V04 | Vaccination records | Reporting to state immunization registries |
Before you lock the list, think about the below four things:
- Direction. Feeds coming into your app get approved faster than feeds going out, because hospitals look much harder at anything that writes into their EHR.
- Version. Hospitals send anything from v2.3 to v2.5.1, and US public health reporting usually expects 2.5.1. Make sure your parser can handle the older versions too.
- Filtering. A busy hospital sends thousands of ADT messages a day. Ask for a filtered feed, such as one department or only the patients in your program, so you don’t store patient data you have no reason to keep.
- Z-segments. Hospitals add their own custom segments, which start with Z, for data the standard doesn’t cover. Ask for these in the interface spec, since they often hold the one field your workflow depends on.
How Does an HL7 Interface Move Data?
Most HL7 v2 messages travel over MLLP (Minimal Lower Layer Protocol) which is nothing but a thin wrapper around an ordinary TCP connection. The sender marks the start of each message with one byte (0x0B) and the end with two bytes (0x1C, then 0x0D). The receiver answers each message with an acknowledgment.
The acknowledgment, or ACK, is what keeps the feed reliable. Its MSA segment carries one of three codes:
- AA (application accept): the message arrived and was processed.
- AE (application error): the message arrived but couldn’t be processed, for example because a required field was blank.
- AR (application reject): the message was refused, often because the message type or version was wrong.
Most senders wait for an ACK before sending another message. If your receiver does not send the ACK, messages can quickly pile up in the hospital’s queue. The receiver should acknowledge the message immediately and then process it. Keep a copy of the original message before parsing it as well, so a mapping problem does not result in lost data.
MLLP has no encryption and no login. Before any patient data moves, your team and the hospital set up a site-to-site IPsec VPN or run MLLP over TLS. Most hospitals will also ask you to sign a BAA (business associate agreement), since your system will be receiving PHI. Expect the network setup to take longer than the code, because firewall changes at a hospital often need sign-off from a change board that meets once a week.
The same rules used for HIPAA compliant software development also apply to the interface. Encrypt any raw messages you store, log who accesses the message viewer, and set a clear retention period you can explain.Some hospitals and labs use SFTP to send batches of HL7 messages every few minutes or hours.. That works for reporting and billing. It’s too slow for anything the care team needs to act on right away.
How Do You Choose a Healthcare Integration Engine?
An integration engine, also called an interface engine, sits between your app and the hospital. It receives HL7 messages, sends each one to the right place, changes fields where needed, handles ACKs and retries, and gives your team a screen to search for and resend messages.Â
With more than one or two interfaces, using dedicated HL7 integration software often costs less than maintaining custom code. The messages themselves are easy to read. The real work is keeping all the live connections running without problems.
| Option | What it is | Where it fits |
|---|---|---|
| Mirth Connect (NextGen) | The most widely used HL7 interface engine, now sold under a paid license | Teams that want the tool most interface analysts already know and don’t mind paying for it |
| Open Integration Engine, BridgeLink | Free, open-source forks of the last open-source Mirth release, under the MPL 2.0 license | Teams that want a free, familiar engine and can support it themselves |
| Rhapsody and Corepoint (Rhapsody Health) | Paid engines common in hospitals and larger vendors | Products that expect many hospital connections and enterprise buyers |
| InterSystems HealthShare Health Connect, Infor Cloverleaf | Large engines that many health systems run in-house | Usually the hospital’s engine rather than yours, but useful to know when you talk to their team |
| Iguana (iNTERFACEWARE), Qvera Interface Engine | Paid engines popular with software vendors | Vendor teams that want to write integration scripts in a common programming language |
| Cloud services | Google Cloud Healthcare API HL7v2 store with its MLLP adapter; Azure Health Data Services $convert-data for turning HL7v2 into FHIR | Cloud-native products that want managed storage and conversion, with some engine logic built around them |
The Mirth change matters if you’re budgeting now. With version 4.6 in March 2025, NextGen moved Mirth Connect from a mix of open-source and paid licenses to a single paid license and stopped publishing source code for new releases, as its GitHub announcement explains. Version 4.5.2 was the last open-source release.Â
If you still run it, plan to buy a license, move to a fork such as Open Integration Engine, or switch engines. It’s hard to justify staying on a version that no longer gets security updates.
Four questions usually help to make the choice:
- How many interfaces will you run in two years? One or two feeds can live in a small service you write yourself. Five or more are worth an engine.
- Who will run it? An engine needs someone who can read HL7 and keep an eye on message queues. If nobody on your team will do that, a managed service or an aggregator may cost less overall.
- Do you also need FHIR? Most modern engines can convert between HL7 v2 and FHIR, which helps if your app stores data as FHIR resources.
- Would an aggregator be easier? Redox and Health Gorilla connect to many health systems through one API and deal with the HL7 on their end. They’re often the quickest way to get your first few customers live. The catch is per-connection fees, which make EHR integration budgets grow with every hospital you add.
How Does an HL7 Integration Project Run, From Spec to Go-Live?
The exact process can vary from one hospital to another, but the steps generally follow the same order.
- Interface spec. Write down and agree on the message types, trigger events, HL7 version, required fields, Z-segments, ACK mode, and expected message volume. If the hospital uses Epic, its interface team works in Epic’s Bridges module and will usually send you their own spec template.
- Connectivity. Set up the VPN or TLS endpoint, swap IP addresses and ports, and confirm a message from the hospital’s test environment can reach you.
- Sample messages. Ask for de-identified samples of every message type, including the messy ones: merged patients, cancelled orders, corrected results, and long free-text notes.
- Mapping. Match each field you use to your own data model, including the code sets for units, result codes and provider IDs. This step usually takes the longest.
- Testing. Run the samples first, then a full test script with the hospital’s analyst watching. Check that ACKs, errors, and retries work the way you agreed.
- Parallel run. Take in production messages for a while without acting on them. Compare what your app would have done with what the hospital recorded, and fix any gaps.
- Go-live and hypercare. Turn it on, watch queues and error rates closely for the first few weeks, and keep a named contact at the hospital.
Testing should have its own plan and budget. The approach described in healthcare software testing works here too, but each test should be based on a real sample message. Test data created from scratch often leaves out the small details that later cause issues in production.
What Breaks in HL7 Integration After Go-Live?
These are the problems we face most often:
- Patient merges. An ADT^A40 message tells you the hospital merged two patient records. If your app ignores it, you end up with duplicate patients or results filed under the wrong person.
- Corrected results. Labs send corrections as new ORU messages with a changed result status. An app that only adds new records and never updates old ones will show the wrong value.
- Quiet format changes. The hospital upgrades its EHR or changes its setup, and a field moves or a new code shows up. Without alerts for unexpected values, nobody notices for weeks.
- Queue backups. When your receiver goes down, ACKs stop and the hospital’s engine holds messages until someone picks up the phone. Track how many messages are waiting and how long it’s been since the last one arrived, along with uptime.
- Timezones and timestamps. HL7 timestamps may or may not include a timezone offset. Mixing the two leads to appointments that show up an hour off twice a year.
- Character encoding. Names with accents or unusual characters come through incorrect when the sender and receiver assume different encodings.
- Storing more PHI than you need. An unfiltered ADT feed fills your database with thousands of records for people who aren’t your users, which raises your breach risk for no gain.
Plan for monitoring and support from day one, the same way web application maintenance covers any live system. An interface that works on launch day still needs regular checks to make sure it continues to work properly.
How Do You Bridge HL7 v2 to FHIR?
Many products store data as FHIR resources but receive HL7 v2 from hospitals. Converting HL7 to FHIR is a mapping job. An ADT message becomes Patient and Encounter resources, and an ORU message becomes Observation and DiagnosticReport resources.
You don’t need to write every mapping yourself. Azure Health Data Services has a $convert-data operation with starter templates for HL7v2 to FHIR R4, and most paid engines include their own converters. Use default templates only as a starting point. Microsoft makes it clear that its default settings are not intended for production environments, so they should be hosted and tested on their own configurations. On top of that, every hospital has its own codes, Z-segments, and data-entry habits, which means custom rules are still needed.
The conversion also runs the other way. If your app writes back to a hospital that only accepts HL7 v2, your engine turns FHIR resources into outgoing messages, such as MDM for documents or ORU for results. Medical device integration with EHR follows the same pattern, since devices produce readings and the hospital expects them as HL7.
What Should You Ask an HL7 Integration Services Partner?
Whether you hire an external team or build the integration in-house, these questions can help you tell the difference between teams that have worked with live interfaces and those that have only used sample files.
- Which hospitals or EHRs have you connected to over HL7 v2, and which message types did those interfaces carry?
- Which integration engine do you use, and how are you handling the Mirth license change?
- How do you handle patient merges, corrected results and cancelled orders?
- What do you monitor after go-live, and who gets alerted when a feed stops?
- How do you set up connectivity with a hospital, and how long does that usually take on their side?
- Where do you keep raw messages, for how long, and who can see them?
Good answers mention specific message types, engines and failure cases. HL7 integration usually goes more smoothly when the team plans for each hospital’s setups and sorts out the spec, the network and the test messages sorted out before anyone writes code.
Frequently Asked Questions
An HL7 interface is a single connection between two systems, with its own message types and settings. By contrast, an HL7 integration engine is the software that runs many interfaces at once and handles routing, field changes, acknowledgments, retries, and message logs.
Yes, it is. Most US hospitals still use HL7 v2 for admissions, orders, results, and scheduling, even when they also provide FHIR APIs. New products often need both.
It is, but not for new versions. Since version 4.6 released in March 2025, Mirth Connect has been sold under a paid license. Version 4.5.2 was the last open-source release, and community forks such as Open Integration Engine carry on from that code under the MPL 2.0 license.
Yes, whenever the messages contain PHI, it needs to be HIPAA compliant, and most do. MLLP has no built-in encryption, so connections run over a VPN or TLS, and the company receiving the data usually signs a BAA with the hospital.
ADT for admissions, discharges, transfers and changes to patient details. ORU is used for results, ORM or OML for orders, SIU for scheduling, MDM for documents and DFT for charges.
It depends mostly on the hospital. The build itself often takes a few weeks, while network approvals, sample messages and testing with the hospital's interface team usually impact the overall timeline.
