HL7^® Reference Guide

HL7 Reference Guide

Learn what HL7 is, read real messages with confidence, and turn that understanding into working interfaces.

HL7 is the language many healthcare systems use when they need to tell each other that something happened. A patient was admitted. A visit was updated. A lab order was placed. A result was finalized. An appointment was booked, cancelled, or moved. A document became available. The message may look like a compact wall of pipes and carets, but underneath it is a workflow event that another system is expected to understand.

This guide is here to make that practical. It explains the core HL7 v2 building blocks, gives you reference pages for messages, segments, data types, fields, and tables, and connects those details to the daily work of building interfaces. Use it with HL7 Soup Web when you want to inspect and understand messages, then use Integration Soup when you are ready to receive, transform, route, validate, and send data between systems.

What HL7 is really for

HL7 v2 is not just a file format. It is a set of message contracts used by hospitals, labs, radiology systems, practice-management systems, billing systems, public-health gateways, registries, pharmacy systems, and many other clinical products. Most v2 interfaces are event driven: one system sends a message, another system accepts or rejects it, and both sides rely on the message structure to agree about what happened.

A useful way to read HL7 is from the outside in:

How to start with HL7

The fastest path is not to memorize every segment. Start with one real workflow and follow it end to end. If you are looking at an ADT feed, learn admission, transfer, discharge, update, cancel, and merge behavior. If you are looking at a results feed, learn how the patient, order, specimen, and observation groups hang together. If you are looking at scheduling, learn how appointments, resources, locations, and personnel are represented.

1. Open a representative message and identify MSH, especially MSH-9, MSH-10, and MSH-12.
2. Work out the business event: admit, update, order, result, appointment change, document filing, billing event, or ACK.
3. Read the message structure page, then check which segments are required by the real receiver, not only by the base standard.
4. Follow the identifiers. Patient, visit, order, accession, placer/filler, account, provider, and message-control identifiers are usually what make support possible.
5. Check table-driven fields. Codes such as patient class, order control, result status, and acknowledgment code often drive behavior.
6. Decide what the receiver should do when data is missing, invalid, duplicated, out of order, or unsupported.
7. Test sequences, not just single happy-path messages.

Use HL7 Soup Web to understand the message

HL7 Soup Web is the place to make an HL7 message readable before you build around it. Open, paste, or load sample messages and use the guide alongside the message view: click into fields, see the segment and datatype context, inspect table-backed values, and compare what the sender wrote with what the receiver expects.

That matters because most HL7 mistakes are not obvious in raw text. A value may be in the wrong component. A field may repeat. A code may be valid HL7 but not valid for this receiver. A message may be structurally parseable but still the wrong workflow event. HL7 Soup Web helps you slow the message down enough to see those problems.

• Filter messages by field value, missing values, validation status, date-like fields, and other practical conditions so a large file becomes a smaller set of messages you can reason about.
• Inspect statistics for a selected path, such as which message types, patient classes, result statuses, facilities, providers, or observation identifiers appear in the current data set.
• Highlight and validate fields while you are learning the interface contract, then turn those rules into a checklist for the real workflow.
• Open individual messages in their own tab, compare variations, copy or download filtered messages, and anonymize samples before sharing them for support or testing.
• Create an interface from a message when the sample you are inspecting should become the starting point for an Integration Soup workflow.

Use Integration Soup to connect systems

Once you understand the message, the next job is operational: receive it, check it, transform it, route it, send it, and support it when something fails. That is where Integration Soup fits. It is the workflow and interface-engine side of the work: taking data from one system and making it safe and useful for another.

In a real interface, Integration Soup is where you make the business decisions visible. Route ADT messages by event, facility, patient class, or destination. Convert local lab codes into the receiver's codes. Turn a sender's gender values into the target system's expected codes. Write selected values to a database or create HL7 from database rows, CSV, JSON, XML, or other sources. Capture inbound messages, transformed outbound messages, ACKs, logs, retries, and exceptions so support staff can see what happened.

This is also where you should separate similar-looking concepts. HL7 tables tell you what a field's code set means. Integration Soup lookup tables are transformation assets: source value in, target value out. Built-in or generated data-table values can help with sample data and anonymized testing. Those are all useful, but they are not the same thing, and keeping them separate makes interfaces easier to explain later.

A practical workflow for your first interface

A good first HL7 workflow usually looks like this:

1. Collect real but safe samples for every event you expect, including cancels, corrections, repeats, and errors.
2. Open the samples in HL7 Soup Web and identify the fields that control routing, mapping, validation, and ACK behavior.
3. Use the guide pages to confirm the message structure, datatype components, table values, and field intent.
4. Create the Integration Soup workflow with an explicit receiver, validation step, transformation, destination sender, and error path.
5. Map data deliberately: identifiers, dates, codes, providers, locations, observations, repeats, and text should be visible in the workflow.
6. Send to a test endpoint, capture the ACK or response, and log enough context that you can replay the support story later.
7. Keep a small de-identified test pack so changes to mappings, lookup tables, or receiver behavior can be checked before go-live.

Tutorial path

If you are just beginning, use this guide for the HL7 concepts and the Integration Soup tutorials for hands-on product workflow:

Where to go in this guide

The main idea

HL7 becomes much less intimidating once you stop treating it as a wall of punctuation. Every message is trying to say: this event happened, here is the patient or business context, here are the values the receiver needs, and here is how both sides should prove that the exchange worked. Use this reference to understand that contract. Use HL7 Soup Web to inspect and test the message. Use Integration Soup to turn the contract into a workflow that connects systems together.