HL7 and FHIR Integration: How Healthcare APIs Actually Connect (and Where They Break)

Most healthcare engineering teams don’t have a data problem. They have a data access problem.

Patient records live across dozens of systems: EHRs, lab platforms, payer databases, and pharmacy networks. Each one uses a slightly different format. Getting them to share records reliably is one of the hardest challenges in digital health.

HL7 FHIR integration is the modern solution. It connects these systems so they can exchange structured health information securely and at scale. This guide covers how HL7 and FHIR work together, the patterns teams use most, the real challenges to expect, and a checklist to scope your project properly.

Key Takeaways

• FHIR is the newest standard from the HL7 family. It does not replace HL7 v2, which still runs most hospital messaging.
• This approach adds a modern API layer on top of existing HL7 v2 infrastructure.
• FHIR R4 (v4.0.1) is the most widely adopted version. R5 is now the latest release from HL7.
• The three most common patterns are SMART on FHIR, CDS Hooks, and bulk export.
• The biggest implementation challenges are legacy data mapping, data quality, and HIPAA compliance.

What Is HL7 FHIR Integration?

HL7 (Health Level Seven International) creates healthcare data standards. Over the decades, they’ve published HL7 v2, HL7 v3, Clinical Document Architecture (CDA), and the FHIR standard (Fast Healthcare Interoperability Resources).

FHIR uses REST APIs, JSON, and XML to represent health records as modular resources: Patient, Observation, Encounter, Medication, and more. Each resource maps to a specific type. Each is accessible via a standard HTTP endpoint.

This is what makes FHIR API integration practical. Any team familiar with modern web development can work with it.

HL7 FHIR integration connects systems using these APIs to exchange patient records across EHRs, apps, payers, and providers. It differs from broader healthcare API integration, which covers any API-based exchange including proprietary vendor endpoints. This approach uses standardized formats defined by HL7 International. This reduces vendor lock-in and aligns with US regulatory requirements.

Two federal mandates have driven adoption:

• The CMS Interoperability and Patient Access Final Rule (CMS-9115-F) requires CMS-regulated payers, including Medicare Advantage organizations, state Medicaid programs, and qualified health plans, to deploy FHIR R4 APIs for patient access and cross-payer data sharing
• The ONC 21st Century Cures Act Final Rule requires EHR vendors to support FHIR-based access and bans information blocking

Major EHR vendors now expose standardized APIs. Engineering teams can access patient records without building custom integrations for every system. Teams working on EHR software development will find the architecture considerations closely related.

When Should You Use HL7 FHIR Integration?

Not every project needs a full FHIR implementation. Here’s when it makes sense.

Use HL7 FHIR integration when you need to: 

• Connect patient-facing apps with EHR data
• Build a patient portal or healthcare mobile app
• Meet CMS cross-payer data sharing mandates
• Provide standardized healthcare API access instead of custom vendor integrations
• Modernize legacy HL7 v2 workflows for external-facing systems
• Support remote patient monitoring or telemedicine platforms

Stick with HL7 v2 when: 

• You’re working entirely within internal hospital systems
• Your EHR vendor doesn’t yet support FHIR APIs
• Legacy system constraints make migration impractical in the near term

In many real-world projects, the answer is both. HL7 v2 handles internal messaging. FHIR handles the API layer that external apps and payers connect to.

HL7 vs FHIR: What Each Standard Solves (and What It Doesn’t)

Before diving into how they work together, it helps to understand what each standard was actually designed to do, and where each one falls short.

HL7 v2.x: The Workhorse of Legacy Systems

HL7 v2 was first published in 1987 and is still the most widely deployed healthcare messaging standard in the world. It uses pipe-delimited, segment-based messages (MSH|EVN|PID|PV1…) transmitted over MLLP, a protocol built for reliable point-to-point delivery inside hospital networks.

It handles core clinical workflows: patient admissions (ADT^A01), lab orders (ORM^O01), lab results (ORU^R01), medication orders, and scheduling. About 95% of hospital EHR systems still communicate internally via HL7 v2.

The limitation: HL7 v2 was designed before the web existed. Every implementation adds local variations. No single authoritative schema exists. Two hospitals running the same EHR vendor may produce different v2 message structures, making cross-organization interoperability very difficult without custom mapping on both sides.

HL7 v3 and CDA: The Ambitious Cousin

HL7 v3 (2003) was an XML-based redesign that never achieved meaningful adoption. Its main output, Clinical Document Architecture (CDA), survives in document exchange workflows such as discharge summaries and continuity-of-care records.

FHIR R4 and R5: The RESTful, JSON-Based Modern Standard

FHIR R4 (v4.0.1, released 2019) is the current baseline for most implementations and the version mandated by CMS-9115-F. R5 was released in 2023 with improvements to subscriptions and cross-version compatibility. Most production systems are still on this version. Greenfield projects should evaluate R5 readiness with target EHR vendors before committing.

The ONC’s 21st Century Cures Act Final Rule (2020) mandated this standard across US healthcare, triggering Epic, Cerner, Meditech, and others to expose standardized FHIR endpoints.

Decision Criteria: When to Pick Which

The important acknowledgment: FHIR does not replace HL7 v2 in most production environments. It sits alongside it. The realistic path is adding a modern API layer on top of existing HL7 v2 infrastructure, not ripping and replacing.

How HL7 v2 and FHIR Work Together

Here’s what most integration guides overlook: HL7 v2 is not going away.

The vast majority of hospital messaging still runs on HL7 v2. ADT messages handle admissions, discharges, and transfers. ORM handles lab orders. ORU handles lab results. These pipe-delimited messages have run reliably for over 20 years. Hospitals are not replacing them.

A modern API layer sits on top. HL7 v2 moves records between systems inside the hospital. External apps get a clean, standardized connection point. This is the core idea behind HL7 FHIR interoperability: the two standards work together, not against each other.

A typical architecture looks like this:

How the Integration Engine Fits In

The integration engine is the bridge between HL7 v2 and the FHIR layer. It handles message parsing, format mapping, transformation, and routing. Tool options and selection criteria are covered in detail in the Common Patterns section below.

FHIR Server Options

Managed services cut operational overhead. Self-hosted HAPI FHIR gives full control over security and compliance configuration.

Common HL7 FHIR Integration Patterns

The integration pattern you choose determines your architecture, tooling, and team’s workload for years.

Point-to-Point vs Hub-and-Spoke vs API Gateway

Point-to-point is the default most teams start with. One system sends directly to another. It works for 1-2 connections but breaks down fast. N systems = N×(N-1)/2 connections. Best for pilots only.

Hub-and-spoke (interface engine model) puts a central engine at the middle. All systems connect to it. The engine normalizes, transforms, and routes messages. Standard architecture for hospitals with 5+ systems. Past 3-4 connections, it is not optional.

API gateway model is the modern approach. Systems expose standardized APIs. A gateway handles auth, rate limiting, routing, and monitoring. This is the architecture CMS-9115-F is pushing the industry toward , and the right choice for greenfield healthcare API integration projects.

Where HL7 Lives vs Where FHIR Lives in the Stack

HL7 v2 lives at ingress. FHIR lives at persist and expose. The integration engine is the bridge between them.

Choosing an Interface Engine

The interface engine handles parsing, transformation, routing, and monitoring. Main options: Mirth Connect (open source, zero cost), Rhapsody (enterprise-grade, higher cost), Cloverleaf (strong in academic medical centers), and InterSystems IRIS (combines engine with data platform). For greenfield systems with no HL7 v2 sources, you can skip the engine. This is the exception, not the rule.

API Gateways for FHIR

An API gateway manages how consuming apps connect to your FHIR server, handling auth, rate limiting, audit logging, and versioning. Managed services (Azure Health Data Services, AWS HealthLake) include built-in management and suit most mid-size implementations. Dedicated gateways (Kong, Apigee) are worth the overhead at enterprise scale.

Saigon Technology’s AxiaGram platform processes over 6 million medical records through this exact architecture: HL7 v2 ingress, interface engine transformation, FHIR-based persistence, and REST API exposure, all under HIPAA-compliant infrastructure with full audit logging.

Patterns at the Consume Layer

SMART on FHIR adds OAuth 2.0-based authorization on top of the base spec. When a clinician opens a SMART app in Epic or Cerner, the EHR passes an authorization token. The app pulls records without the clinician logging into a separate system. Use cases: patient portals, clinical decision support tools.

CDS Hooks push real-time guidance into EHR workflows at specific trigger points. Use cases: drug interaction alerts, care gap notifications, prior authorization checks.

Bulk FHIR Export ($export) exports large patient populations asynchronously as structured JSON files. Use cases: population health analytics, cross-payer reporting under CMS mandates, research datasets.

Real-World Integration Scenarios

Understanding the patterns is one thing. Seeing how they map to actual clinical workflows is where projects succeed or fail.

EHR-to-EHR Exchange

The most common scenario: Epic sending ADT^A08 (patient update) or ADT^A28 messages to Cerner via HL7 v2. The engine validates segments, maps fields, and forwards via MLLP. Both vendors support FHIR APIs, but their implementations have quirks. Never trust the spec alone. Test against the actual target system.

Lab Results Into Clinical Workflows

Lab systems send results via ORU^R01, one of the highest-volume message types in any hospital. The mapping takes ORU^R01 to the Observation resource (with a DiagnosticReport wrapper). A mis-mapped LOINC code or missing reference range can appear in the wrong clinical context. Result routing is the key concern: messages must reach the ordering clinician, not just the ordering system.

Imaging Integration

Radiology systems use DICOM for image storage and HL7 v2 for workflow messaging. The FHIR ImagingStudy resource bridges the two. A typical flow: the EHR sends an ORM^O01 order to the RIS, the PACS stores images in DICOM, the RIS returns a result via ORU^R01, and the ImagingStudy resource provides a structured reference for apps to consume.

This scenario spans three protocols: HL7 v2, DICOM, and FHIR. Teams need experience across all three.

Patient-Facing Apps via SMART on FHIR

This is the scenario CMS-9115-F was designed to enable. The authorization flow is covered in the SMART on FHIR section above. What that section does not cover is what happens after the API call succeeds.

EHR FHIR APIs often return incomplete or inconsistently coded data. Missing fields, unexpected code systems, and pagination edge cases are common in production. Build defensively and assume the data is incomplete until proven otherwise.

Key Challenges in HL7 FHIR Integration

In our work building health applications, including systems that process over 6 million medical records, these challenges come up most.

Legacy Data Mapping

HL7 v2 segments don’t map 1:1 to FHIR resources. An ADT message carries demographics in PID, visit info in PV1, and insurance in IN1. Mapping these to Patient, Encounter, and Coverage resources takes custom logic that needs ongoing maintenance as upstream systems change.

Many hospitals add Z-segments (custom fields) with no standard mapping. Each needs a tailored solution. Moving between versions, such as DSTU2 to R4, can break existing integrations. Backward compatibility is not guaranteed. Mapping to terminologies like SNOMED-CT, LOINC, and ICD-10 adds further complexity teams often underestimate.

Data Quality and Inconsistency

Real-world HL7 v2 records are messy. Missing fields, non-standard codes, bad date formats, and duplicates are common in production. Validation is strict, a server rejects non-conformant resources. You need a cleansing layer before ingestion. But remediation falls to your team, not the platform.

HIPAA Compliance Across the Stack

Every layer of the pipeline must protect Protected Health Information (PHI). The HIPAA Security Rule sets the legal baseline. See our guide on HIPAA-compliant app development for details. At minimum, every integration needs:

• Business Associate Agreements (BAAs) with every vendor
• Encryption in transit (TLS 1.2+) and at rest (AES-256)
• Audit trails for every PHI access event
• Role-based access with minimum necessary access

Saigon Technology’s projects run under ISO 27001 and HIPAA/HITECH frameworks with Zero Trust Architecture. For more context, see our overview on healthcare data security.

FHIR Profile Variations

US Core, Da Vinci, and USCDI each add constraints on top of base spec. An integration built to base spec may fail against a US Core endpoint. Add Touchstone conformance testing to every plan.

How to Plan an HL7 FHIR Integration Project

A solid discovery phase prevents most failures. This checklist covers the key decisions at each stage.

Discovery

[ ] Identify data sources: HL7 v2, HL7 v3, or CDA? Which message types?

[ ] Identify EHR vendors and which version of the interoperability standard they support (DSTU2, STU3, R4, R5)

[ ] Identify which profiles are required (US Core, Da Vinci, custom IG)

[ ] Map patient access and cross-payer exchange requirements per CMS-9115-F

Architecture

[ ] Choose a pattern: SMART, CDS Hooks, bulk export, or custom API integration

[ ] Select an integration engine based on infrastructure and message volume

[ ] Choose a server to host the API layer: self-hosted or managed (Azure, AWS, GCP)

[ ] Define which resources to support

Data Mapping

[ ] Map HL7 v2 segments to the standard API resources for each message type

[ ] Identify Z-segments and plan how to handle them

[ ] Map standard terminologies (SNOMED-CT, LOINC, ICD-10)

[ ] Plan for data quality edge cases

Compliance

[ ] Sign BAAs with all vendors

[ ] Set up audit logging for PHI access

[ ] Add encryption in transit and at rest

[ ] Define access control and minimum necessary access rules

Testing

[ ] Validate resources using the standard API validator

[ ] Run conformance testing via Touchstone

[ ] Test against EHR vendor sandboxes

[ ] Review HIPAA compliance across the full stack

Monitoring

[ ] Set up API error tracking

[ ] Build quality monitoring dashboards

[ ] Monitor PHI access logs

[ ] Plan for version migration

FAQs

Is FHIR replacing HL7 v2?

No. Most hospital systems will run both for the foreseeable future. HL7 v2 still runs ~95% of hospital internal messaging and shows no sign of disappearing. FHIR is being added as a modern API layer on top, covering patient-facing access, payer APIs, and new integrations.

The practical reality is a hybrid architecture: HL7 v2 handles internal workflows, FHIR handles external API access. Replacing v2 entirely means reconfiguring decades of embedded hospital infrastructure. For most organizations, that ROI does not exist.

What’s the difference between SMART on FHIR and plain FHIR?

Plain FHIR defines the data model and REST API structure. It standardizes what data looks like and how to query it. What it does not define is how apps authenticate or get authorized to access that data.

SMART on FHIR fills that gap. It adds an OAuth 2.0-based authorization and launch context layer on top of the base spec. Key features:

• Standardized permission scopes (e.g., patient/Patient.read, patient/Observation.read)
• A launch sequence that opens apps from within an EHR with patient context already loaded
• Single auth integration that works across any SMART-enabled EHR vendor

Without SMART, each EHR vendor handles authentication differently, requiring custom integration per vendor. With SMART, a third-party app can launch from Epic, Cerner, or any compliant EHR using the same authorization flow.

How long does an HL7 FHIR integration take?

A single EHR API wrapper takes 4 to 8 weeks. A SMART on FHIR app takes 6 to 12 weeks. A full HL7 v2 migration takes 3 to 9 months. A proper discovery phase gives the most accurate estimate before you commit.

Do I need an interface engine for FHIR-only integrations?

Greenfield systems (no HL7 v2): No. Connect directly to the APIs. Any legacy HL7 v2 involved: Yes. It handles HL7 v2 message parsing, transformation into FHIR resources, and routing. Past 3 to 4 connected systems, routing complexity alone justifies it.

What does healthcare API integration typically cost?

Key cost drivers: number of connected systems, data quality remediation, HIPAA build-out, profile variations per trading partner, and ongoing mapping maintenance. A scoped discovery phase ($5,000 to $15,000) typically saves 2 to 3 times that cost in avoided rework.

Conclusion

HL7 FHIR integration is now a baseline for teams building health applications. CMS mandates, EHR vendor support, and patient access rules have made it the default for new interoperability work. HL7 v2 isn’t going away. The practical path is a modern API layer that bridges legacy systems with current ones.

Teams that get this right start with a rigorous discovery phase. They plan mapping with buffer for real-world messiness. They build HIPAA compliance in from day one, not as an afterthought.

Saigon Technology has built healthcare solutions across HL7 FHIR integrations, remote patient monitoring, and clinical data pipelines. We’ve delivered HIPAA-compliant architecture across 850+ projects over 14+ years, with Microsoft Gold Partner status and ISO 27001 certification.

If you’re planning this type of project and want an experienced team from discovery onward, get in touch.