EHR Integration Explained: HL7 v2 and FHIR

EHR integration is the work of moving patient, scheduling, clinical, document and billing data between your application and an electronic health record system, reliably and under HIPAA. In practice it means two technologies: HL7 v2, the message-based standard that hospitals and practices have run for decades, and FHIR, the REST API standard that certified EHRs now expose. Most real projects use both, plus document exchange through health information exchanges (HIEs). This guide explains how each works, the data flows you will be asked for, the security and authentication rules, how to test an interface, and what a health-tech vendor must have ready before the first connection.

Why integration is the hard part

Building a healthcare application is a known problem. Connecting it to the EHR a practice or hospital already runs is where timelines slip, because the hard parts are not in your code.

• Every EHR is different. The standards are shared; the implementations are not. One system populates the insurance segment in an HL7 message, another leaves it empty and expects an API call. Two conformant FHIR servers can still disagree on which search parameters they support.
• Patient matching has no universal key. The US has no national patient identifier. Each organization has its own medical record numbers, and matching across them relies on demographics, identifiers and probabilistic rules. Getting this wrong attaches one patient’s results to another’s chart.
• The data is messy. Free-text allergies, local lab codes instead of LOINC, medications without RxNorm codes, dates in several formats. Mapping and normalization are most of the effort.
• Access is governed. Connecting to an EHR means an agreement with the provider organization, often an application review with the EHR vendor, a business associate agreement, and sometimes a fee. These take calendar time.
• Nothing is static. EHR upgrades change message formats and API behavior, so an interface needs monitoring and an owner.

Teams that treat integration as a feature to add before launch usually discover it is a program that starts at design time.

HL7 v2 vs FHIR

HL7 v2 and FHIR are both products of HL7 International, but they come from different eras and solve the exchange problem in different ways. The hl7 vs fhir question is rarely either-or; it is which one the system you are connecting to supports for the data you need.

HL7 v2 in brief

HL7 v2 is a pipe-delimited text format sent as discrete messages when an event happens. A message is made of segments (MSH for the header, PID for patient identification, PV1 for the visit, SCH for a schedule slot, OBR and OBX for orders and observations, DG1 for diagnoses, IN1 for insurance). The message type and trigger event live in MSH-9, for example ADT^A04 for an outpatient registration or ORU^R01 for a lab result.

Messages travel over MLLP, a thin framing protocol on TCP, usually inside a VPN, and the receiver returns an ACK. Interface engines such as Mirth Connect route, filter and transform messages between systems, and most hospital integration teams expose HL7 v2 feeds through one. Custom Z-segments carry data the standard does not define, which is one reason no two feeds look alike.

FHIR in brief

FHIR (Fast Healthcare Interoperability Resources) models healthcare data as resources (Patient, Practitioner, Encounter, Appointment, Observation, Condition, MedicationRequest, AllergyIntolerance, Immunization, DiagnosticReport, DocumentReference, Coverage) exchanged as JSON or XML over a REST API. You read a patient with GET /Patient/{id}, search with GET /Observation?patient={id}&category=laboratory, and receive results in a Bundle.

FHIR R4 is the version in production use. US Core profiles constrain the resources to what US systems must support, aligned with the USCDI data classes, and ONC certification criteria for certified health IT require a standardized FHIR R4 API for patient and population access. SMART on FHIR adds the app-launch and authorization layer, and the Bulk Data Access specification adds population-level export in NDJSON files.

Aspect	HL7 v2	FHIR R4
Model	Event-driven messages pushed from the EHR when something happens	Resources read and written on request through a REST API, plus optional subscriptions and bulk export
Format	Pipe-and-caret delimited text, segments and fields by position	JSON or XML, self-describing, with profiles and terminologies
Transport	MLLP over TCP, typically within a VPN; ACK per message	HTTPS with OAuth 2.0 (SMART on FHIR) or signed JWTs for system-to-system access
Typical uses	Real-time ADT, scheduling, orders, results and charge feeds inside and between provider organizations	Patient-facing apps, clinician apps launched inside the EHR, analytics exports, payer and consumer data access
Strengths	Universal in hospitals, proven at volume, push-based so your system learns about events immediately	Modern tooling, standard authorization, consistent data model, easier onboarding through vendor developer programs
Limits	Vendor variations, no built-in encryption, custom segments, hard to query historical data	Write support varies widely by vendor; not every data element is exposed; rate limits and app review processes

A practical rule: if you need to know the moment a patient is admitted, scheduled or has a result, ask for HL7 v2 feeds. If you need to read a chart on demand, write back to it, or launch inside the clinician’s workflow, use FHIR. Many fhir integration services projects still carry an HL7 v2 feed alongside, because FHIR servers rarely push events.

Common data flows

Most ehr integration projects involve a handful of flows. Naming them precisely in your requirements saves weeks of back-and-forth with the vendor’s integration team.

Patient demographics and registration

An ADT feed (A04 register, A08 update, A03 discharge, A40 merge) keeps your patient list in sync and tells you when two records were merged. In FHIR, the same data comes from the Patient resource, with Coverage for insurance.

Scheduling

SIU messages (S12 new appointment, S13 rescheduled, S14 modified, S15 cancelled, S17 deleted, S26 no-show) drive telehealth links, reminders, intake forms and waiting-room logic. FHIR exposes Appointment, Slot and Schedule, and some servers accept appointment booking through them.

Orders and results

ORM (and the newer OML) messages carry orders; ORU^R01 messages carry results, with each OBX segment one observation coded, ideally, in LOINC. In FHIR, ServiceRequest, Observation and DiagnosticReport cover the same ground.

Clinical documents

MDM^T02 messages deliver a document notification with content, usually a PDF or a C-CDA. FHIR uses DocumentReference with the document in a Binary resource. Transition-of-care summaries move as C-CDA documents through HIE networks or Direct Secure Messaging.

Medications, allergies, problems and immunizations

These are mostly read through FHIR (MedicationRequest, AllergyIntolerance, Condition, Immunization), with RxNorm, SNOMED CT, ICD-10-CM and CVX as the vocabularies. Immunization registries also accept VXU^V04 messages over HL7 v2.

Charges and billing

DFT^P03 messages post charges from a clinical system to a practice-management or billing system. Payer-side flows use X12 EDI (270/271 eligibility, 837 claims, 835 remittance) rather than HL7, through a clearinghouse.

Outside records through an HIE

Regional HIEs and the national frameworks (Carequality, CommonWell, eHealth Exchange and TEFCA) let a connected organization find a patient across other organizations (patient discovery) and query for their documents, using IHE profiles under the hood. Access is organization-level and governed by participation agreements, so an app usually reaches an HIE through its customer’s membership rather than its own.

Security and authentication

An interface moves protected health information, so the HIPAA Security Rule’s technical safeguards apply end to end: access control, audit controls, integrity, person or entity authentication and transmission security.

• HL7 v2 transport. MLLP has no encryption of its own. Feeds run inside a site-to-site VPN or over a TLS-wrapped connection, with IP allow-lists on both ends. Message control IDs (MSH-10) and ACK handling prevent silent loss or duplication.
• FHIR authorization. SMART on FHIR uses OAuth 2.0. A user-facing app runs the authorization-code flow with PKCE, either launched from inside the EHR (an EHR launch, which passes the current patient and user as context) or started on its own (a standalone launch). Scopes limit what the token can reach, for example patient-level read access to Observation resources, and the openid and fhirUser scopes identify the signed-in user. Refresh tokens require the offline_access scope and the server’s consent.
• System-to-system access. The SMART Backend Services profile covers servers that talk to the FHIR API without a user present: your system signs a JWT with its private key, presents it to the token endpoint and receives a short-lived access token with system-level scopes. Public keys are registered with the EHR in advance, often as a JWKS URL.
• Audit. Log every message received and every API call made, with who, what, when and which patient, in a store your privacy officer can search. FHIR’s AuditEvent resource is one model for this. Never log the PHI payload itself in application logs.
• Agreements. A business associate agreement with the provider organization, and often an agreement with the EHR vendor’s app program, which may include a security questionnaire, a review of your app and a sandbox-to-production promotion process. Check the current official text of the HIPAA rules and your vendor’s program terms; this is general information, not legal advice.

Testing an EHR interface

Interfaces fail in ways unit tests do not catch.

1. Use synthetic data from the start. Synthea generates realistic patient populations, and public FHIR test servers and vendor sandboxes let you develop without real PHI, which never belongs in a test environment.
2. Validate messages and resources. Run HL7 v2 messages through a validator and your interface engine’s test channels; validate FHIR resources against US Core profiles. ONC’s Inferno test kit checks a FHIR server against the certification requirements and is useful for understanding what a conformant server must support.
3. Test the ugly cases. Out-of-order events (a cancellation arriving before the appointment it cancels), duplicate control IDs, patient merges, empty or malformed segments, results that are corrected after release, time zones and daylight-saving boundaries, and tokens that expire mid-session.
4. Load and backlog. Replay a day’s volume of messages in minutes to see how your queue, database and matching logic behave, and confirm the interface recovers after an outage without losing or duplicating messages.
5. End-to-end with the customer. A user-acceptance round with the practice or hospital, in their test environment, with their interface team watching the engine. Their sign-off is the real exit criterion.
6. Monitor in production. Message counts, ACK failures, API error rates, token refresh failures and matching exceptions, with alerts to a named owner.

What to prepare

EHR integration services move faster when the vendor arrives prepared. Before you ask a practice, a hospital or an EHR vendor for a connection, have the following ready:

• A one-page data map: which data elements you need, in which direction, how often, and what you do with them.
• Your regulatory posture: a signed-ready BAA template, a completed security questionnaire, a HIPAA risk analysis summary, and your policies for access, logging, incident response and data retention.
• A patient-matching policy: which identifiers you accept, what happens on a partial match, who resolves exceptions.
• Technical readiness: a public key or JWKS endpoint for SMART Backend Services, a redirect URI and app metadata for SMART app launch, VPN details and a static IP for HL7 feeds, and a receiving service that can ACK messages.
• A test environment the customer can connect to, with synthetic data, and a documented promotion process to production.
• Named owners on both sides, a support channel, and an agreement about what happens when the EHR is upgraded.
• A fallback workflow for the practice when the interface is down, agreed before go-live.

If your product stores or processes PHI, the broader controls in our HIPAA-compliant software development guide apply as well, and the data definitions and stewardship questions in data governance in healthcare will come up as soon as two systems disagree about a field. Telehealth products have their own integration list, covered in the telemedicine app development guide.

Where PS3G fits

PS3G builds and maintains EHR integrations as part of our healthcare software development services: HL7 v2 feeds through interface engines, FHIR R4 and SMART on FHIR applications, HIE document exchange, and the X12 flows on the billing side, for clinics, health-tech companies, device makers, labs and payers of every size. We also run our HIPAA-compliant EHR and telehealth platform, DocVilla, so we have sat on both sides of the interface: as the EHR being connected to and as the vendor asking for a connection. For the systems around the EHR (payment, CRM, analytics, scheduling, identity), our API development and integration services cover the same discipline outside healthcare standards.

Related reading

• HIPAA-Compliant Software Development: Requirements & Checklist
• Telemedicine App Development: Features, Compliance, Cost Drivers
• Data Governance in Healthcare: HIPAA, Quality, Interoperability
• Healthcare software development services

Frequently asked questions

What is the difference between HL7 and FHIR?

HL7 v2 is an older, message-based standard: the EHR pushes pipe-delimited messages when events happen, such as a registration or a lab result. FHIR is a newer REST API standard: your application reads and writes JSON resources such as Patient and Observation on request, with OAuth 2.0 authorization through SMART on FHIR. Hospitals rely on HL7 v2 for real-time feeds; certified EHRs expose FHIR R4 APIs for app and patient access.

How long does EHR integration take?

The engineering for a well-defined flow is often a matter of weeks. The calendar time is usually set by the other parties: the provider organization’s agreements and security review, the EHR vendor’s app program and sandbox access, and scheduling the interface team’s time for testing. Projects that start with a data map, a BAA and a test environment ready move faster than those that start with a request for a connection.

Do we need an interface engine?

For HL7 v2 feeds, usually yes. An engine such as Mirth Connect receives messages, acknowledges them, transforms vendor-specific formats into your model, queues them for retries and gives you monitoring. For a product that connects only through FHIR APIs, an engine is optional; a well-built integration service with queuing, retries and logging does the same job.

What is SMART on FHIR?

SMART on FHIR is the specification that defines how an application authenticates and authorizes against a FHIR server using OAuth 2.0 and OpenID Connect. It covers apps launched from inside the EHR with patient and user context, standalone apps, scopes that limit data access, and a backend profile for system-to-system access using signed JWTs. It is what lets one app work across many certified EHRs with the same authorization code.

Can a small practice’s EHR be integrated, or only hospital systems?

Certified ambulatory EHRs are required to expose FHIR R4 APIs for patient and population access, so most practice systems can be integrated through FHIR, and many also offer HL7 v2 interfaces or vendor APIs. The practical limits are the vendor’s app program terms, which data elements are exposed, and whether write access is supported. Ask the vendor for its API documentation and sandbox before committing to a design.