FHIR R4 Integration: The Complete Guide (2026)

If you are building anything new that touches healthcare data in 2026 — a clinical app, a patient-engagement platform, a remote-monitoring service, a population-health tool, a mobile-first EHR companion — you will be building on FHIR. Not because it is fashionable, but because the alternative (raw HL7 v2 plus custom EHR SDKs) no longer makes economic sense for greenfield work. Every major EHR now ships FHIR R4 endpoints, federal regulation mandates them, and the tooling ecosystem has finally caught up with the promise of the standard.

This pillar walks through FHIR end-to-end: the model, the REST patterns, the security layer, the US-specific profiles, the compliance regime, and the practical engineering decisions that separate successful FHIR projects from the wreckage of over-ambitious ones. Pair it with our companion pillars on Mirth Connect and HL7 v2 integration — most production healthcare systems need all three.

1. What Is FHIR?

FHIR — pronounced "fire" — stands for Fast Healthcare Interoperability Resources. It is a standard published by Health Level Seven International for exchanging electronic health information.

Three design choices distinguish FHIR from everything that came before:

1. REST-native. FHIR is built around HTTP verbs (GET, POST, PUT, DELETE, PATCH) against well-defined URLs. A developer who has built a REST API can understand FHIR's transport layer in an afternoon.
2. JSON-first. FHIR resources are most commonly serialized as JSON (XML is also supported but rarely used in new work). This is a radical departure from the XML- and pipe-delimited predecessors.
3. Resources, not messages. Where HL7 v2 thinks in messages (an ADT^A01 about a specific event), FHIR thinks in resources (a Patient that exists and can be read, updated, or referenced). This REST-ful resource model is what makes FHIR work naturally with modern applications.

The practical consequence is simple: a FHIR API looks like any other well-designed REST API your developers have consumed. GET /Patient/123 returns a Patient. POST /Observation creates an Observation. GET /Patient?name=Smith searches for patients named Smith. The surprise, if you come from HL7 v2, is how ordinary it feels.

2. FHIR's History and Versions

FHIR's evolution matters because you will encounter all of these versions in the wild.

FHIR R4 is the target you should plan around.Every US regulatory mandate under the ONC Cures Act is written against R4. Every major EHR's production FHIR API is R4. R5 exists and will matter over time, but if you build to R4 today you are building to the standard the US healthcare system is actually using.

Continued growth in FHIR adoption is well-documented — our article FHIR Adoption Is Surging: What 2025 Data Tells Us covers the latest numbers and what they mean for implementers.

3. The FHIR Data Model: Resources and References

FHIR's model can be summarized in four ideas.

3.1 Resources

A resource is a self-contained unit of healthcare information — a Patient, an Observation, a Medication, an Encounter, a Practitioner. FHIR R4 defines 145 resource types, covering everything from clinical administrative data (Patient, Practitioner, Organization) to clinical observations (Condition, Procedure, AllergyIntolerance) to workflow (Encounter, Appointment, ServiceRequest) to financial data (Coverage, Claim, ExplanationOfBenefit).

Each resource has a defined structure with required and optional fields, and each field has a declared data type.

3.2 References

Resources link to each other via references. An Observation references the Patient it concerns. A MedicationRequest references both the Patient and the Practitioner who prescribed it. References are URLs.

{
  "resourceType": "Observation",
  "id": "obs-001",
  "status": "final",
  "code": { "coding": [{ "system": "http://loinc.org", "code": "8867-4", "display": "Heart rate" }] },
  "subject": { "reference": "Patient/123" },
  "valueQuantity": { "value": 72, "unit": "beats/minute" },
  "effectiveDateTime": "2026-04-17T10:30:00-05:00"
}

3.3 Extensions

Real-world data doesn't always fit the base specification. Extensions let implementations add fields without breaking the core model. Every FHIR resource supports extension and modifierExtension arrays, and implementations publish extension definitions so consumers know what to expect.

3.4 Profiles

A profile is a constrained version of a resource tailored to a specific use case. US Core Patient is a profile of Patient that adds required fields (race, ethnicity, birth sex) for US clinical interoperability. Profiles are what make FHIR viable across wildly different healthcare contexts — the base standard is flexible; profiles make it concrete.

4. The Major FHIR Resources You'll Actually Use

Of the 145 FHIR resources, fewer than 20 show up in most production systems. The ones to learn first:

4.1 Clinical administrative

4.2 Encounters and workflow

4.3 Clinical data

4.4 Medications

4.5 Documents and narrative

Master those 20 and you can build most real-world FHIR integrations. Everything else is a specialization.

5. FHIR as a REST API

The FHIR RESTful API is the most immediately practical part of the standard. It follows conventional REST patterns.

5.1 CRUD operations

Against a base URL (e.g., https://fhir.example.com/r4/), FHIR defines:

5.2 MIME types

FHIR uses dedicated MIME types so servers can advertise their format:

• application/fhir+json — JSON (default in practice)
• application/fhir+xml — XML (rare in new work)

5.3 Operation outcomes

When something goes wrong, FHIR servers return an OperationOutcome resource with structured error information — not a free-text error string. This makes error handling programmatic rather than guesswork.

5.4 Capability statements

Every FHIR server publishes a CapabilityStatement at /metadata declaring:

• Which resources it supports
• Which operations (read, search, create, update) are allowed per resource
• Which search parameters work
• Which profiles the server conforms to
• Which security methods are required

Always read the CapabilityStatement firstbefore integrating with any new FHIR endpoint. It tells you what the server will and won't do.

6. Bundles and Transactions

A Bundle is a FHIR resource that contains other resources. It is how FHIR does collections, transactions, and document exchange.

Bundle types include:

The most useful in practice is the transaction Bundle— it lets you create, update, and delete multiple resources in a single atomic request. Need to create a Patient, three Observations, and an Encounter in one call that either all succeeds or all fails? That's a transaction Bundle.

7. FHIR Search

FHIR's search API is where the standard genuinely shines. Every resource has a defined set of search parameters that are consistent across implementations.

7.1 Basic search

GET /Patient?name=Smith&birthdate=1972-05-12&gender=male

7.2 Modifiers and prefixes

Search values can be modified:

• name:exact=Smith — exact match
• birthdate=gt1970-01-01 — greater than
• name:contains=smi — contains
• code:in=http://loinc.org|test-codes — value set filter

7.3 Chained search

Search across references:

GET /Observation?subject.name=Smith&code=http://loinc.org|8867-4

7.4 Include and revinclude

Pull referenced resources in the same response:

GET /MedicationRequest?patient=123&_include=MedicationRequest:medication

7.5 Composite and special searches

Composite parameters let you search combinations (e.g., component-code-value-quantity on Observation) that would be cumbersome otherwise.

8. SMART on FHIR and OAuth 2.0

FHIR itself says nothing about how to authenticate. SMART on FHIR is the standard that fills that gap, layering OAuth 2.0 and OpenID Connect onto FHIR endpoints.

SMART on FHIR defines two primary launch patterns:

8.1 EHR launch

A clinician working in an EHR clicks a button that launches a third-party app. The EHR passes context (current patient, current encounter, current user) to the app along with OAuth tokens. The app reads and writes to the EHR's FHIR API using those tokens.

This is how most Epic, Cerner, and athenahealth third-party clinical apps work.

8.2 Standalone launch

A user opens a patient-facing app directly on their phone. The app initiates an OAuth authorization flow against the EHR's FHIR authorization server, the patient logs in, consents to the scopes being requested, and returns to the app with an access token.

This is how most patient-access apps work — the pattern mandated by the ONC Cures Act for patient-facing FHIR access.

8.3 Scopes

SMART scopes look like patient/Observation.read (read observations for the patient in context) or user/Patient.* (full access to all patients the user can see). The granularity is deliberate — apps should request the minimum scopes they need.

A working SMART launch is more fiddly than the marketing suggests. Between EHR-specific quirks, token refresh logic, and PKCE configuration, most teams lose a week the first time.

9. CDS Hooks

CDS Hooksis a companion specification that lets third-party services inject clinical decision support into an EHR's workflow at specific trigger points — the moment a medication is ordered, the moment a patient chart is opened, etc.

When a trigger fires, the EHR calls a registered CDS service with the relevant FHIR context. The service responds with cards— small pieces of decision support the EHR displays in its UI (e.g., "Warning: patient has documented allergy to this medication class" or "Recommend referral to cardiology based on lab trends").

CDS Hooks is powerful but less commonly deployed than SMART apps. If your use case includes clinical alerts, guideline adherence, or genomics-driven decision support, it is worth understanding.

10. US Core: The American FHIR Profile

Base FHIR R4 is intentionally flexible. US Core is the official US profile that constrains FHIR into something every American EHR vendor and every American app can interoperate against.

US Core (currently at version 6.1) defines:

• Required profiles for Patient, Practitioner, Organization, Condition, Observation (with multiple profiles for vitals, lab results, social history), Encounter, Immunization, AllergyIntolerance, MedicationRequest, and many others.
• Must-support fields — fields that certified systems must at least handle, even if the data is occasionally unavailable.
• Value sets — the terminologies each field must use (LOINC, SNOMED CT, RxNorm, ICD-10-CM).
• Search parameter requirements — which searches every US Core server must support.

Every US-certified EHR's FHIR API conforms to US Core. If you are building an app that needs to work across Epic, Cerner, and athenahealth, you should build against US Core, not against vendor-specific APIs.

11. The ONC 21st Century Cures Act

The 21st Century Cures Act Final Rule, published by the Office of the National Coordinator for Health IT (ONC) in 2020, is the single most important US regulation for FHIR implementers.

Key mandates:

• Certified EHRs must expose FHIR R4 APIs to patients, conformant to US Core.
• APIs must be accessible without special effort — no custom contracts, no per-integration fees for patient access.
• Information blocking is prohibited — healthcare actors cannot unreasonably interfere with access, exchange, or use of electronic health information.
• Enforcement is real — the HHS Office of the Inspector General can impose civil monetary penalties on IT developers and health information networks that engage in information blocking.

If you sell an app that reads patient data from US EHRs, you benefit from the Cures Act. If you build an EHR or health IT product that sells to US customers, you must comply with it.

12. FHIR Servers: HAPI, Azure, Google, AWS

You rarely need to implement a FHIR server from scratch. Mature options:

12.1 HAPI FHIR (open source)

The reference open-source Java server, maintained by Smile CDR. Feature-complete, widely deployed, and free under Apache 2.0. Suitable for production with appropriate hardening.

12.2 Smile CDR (commercial)

Enterprise-grade FHIR server built on HAPI by the same maintainers, with commercial support, advanced modules, and consulting. Common in HIEs and health systems.

12.3 Microsoft Azure Health Data Services

Azure's managed FHIR offering (evolved from the former "Azure API for FHIR"). Good fit for shops already on Azure; strong DICOM + MedTech Analytics integration.

12.4 Google Cloud Healthcare API

GCP's managed FHIR service. Strong integration with BigQuery for analytics and Vertex AI for ML workloads.

12.5 AWS HealthLake

Amazon's managed FHIR service, with built-in natural-language processing over clinical notes.

12.6 Firely Server

Commercial .NET-based FHIR server, popular in European deployments.

Choosing between them depends on cloud preference, budget, compliance posture, and whether you need a FHIR data store or a FHIR façade. If you are integrating FHIR with an existing HL7 v2 environment, Mirth Connect plus a dedicated FHIR store is the pattern we most commonly recommend — see our Mirth FHIR Server offering for how that pairing works in practice.

13. FHIR vs HL7 v2: Migration Strategy

One of the most common questions we get: "Should we migrate from HL7 v2 to FHIR?"

The honest answer is rarely a full migration — almost always a hybrid.

13.1 Where FHIR wins

• New patient-facing apps (Cures Act mandates FHIR for this).
• Mobile and web clinical apps (SMART on FHIR is the lingua franca).
• External data sharing with partners and HIEs.
• Analytics and bulk data export (FHIR's $export operation is designed for this).
• Anywhere you want a REST API that modern developers can consume.

13.2 Where HL7 v2 still wins

• High-volume system-to-system messaging inside a hospital (lab feeds, ADT feeds).
• Legacy integrations to existing interfaces that work fine and aren't worth rebuilding.
• Edge cases FHIR doesn't yet model well (some pharmacy and financial flows).

13.3 The practical pattern

Keep your v2 interfaces running. Put a FHIR façade in front of them (this is where Mirth Connect becomes invaluable). Expose FHIR for new consumers; route to v2 under the hood. Over time, migrate individual interfaces as the business case justifies — never all at once. Our article on Mirth Connect + FHIR: Powering the Next Generation of Healthcare Data Exchange walks through the façade pattern in detail.

14. Common FHIR Implementation Challenges

The FHIR landscape is mature, but projects still go sideways in predictable ways.

14.1 Vendor-specific deviations

Base FHIR is consistent. Vendor-specific extensions are not. Epic's Observation carries Epic extensions; Cerner's carries Cerner extensions. Write against US Core, but test against every EHR you target. Vendor specifics are covered in our individual guides — Epic EHR integration and Cerner EHR integration.

14.2 Sandbox vs production gaps

Vendor sandboxes are rarely production-realistic. Data shape, performance, and rate limits all differ. Plan for a dedicated integration phase with each production tenant.

14.3 OAuth/SMART fragility

Token refresh, PKCE, EHR-specific launch URLs, and scope negotiation all break in subtle ways. Budget time specifically for authentication integration testing.

14.4 Rate limits

Every hosted FHIR API rate-limits. Bulk operations that work in development at 10 requests/second fail silently in production when the limit is enforced. Batch with Bundles; use $export for bulk.

14.5 Data volume

Real patient records can include thousands of Observations and hundreds of MedicationRequests. Naïve pagination will kill your mobile app. Use _elements, _summary, and targeted searches.

14.6 Bulk export

The FHIR $export operation is the correct way to pull large volumes of data. It is asynchronous and requires handshake-style client logic — very different from CRUD.

14.7 Terminology normalization

FHIR specifies value sets (LOINC, SNOMED CT, RxNorm), but vendors sometimes ship local codes alongside standards. Map defensively; log the unmapped codes and review them periodically.

14.8 Provenance and audit

Regulated workflows need to track who did what with which resource when. FHIR provides Provenance and AuditEvent resources for this. Use them from day one; retrofitting audit logging is painful.

15. When to Bring in FHIR Expert Help

You should bring in specialists when any of the following apply:

• You're certifying against ONC — first-time certification is notoriously fiddly.
• You need to integrate with multiple EHR vendors and want to ship before your runway burns.
• Your team has never shipped a production SMART on FHIR app and you have a hard customer deadline.
• You're building a FHIR façade in front of legacy HL7 v2 and don't have production Mirth Connect experience.
• You need HIPAA, HITRUST, or SOC 2 attestations on an integration layer that currently has none.
• You need to process bulk FHIR data at scale and your team hasn't used $export in anger.

Our FHIR integration services and FHIR development solutions teams have shipped FHIR implementations for hospitals, reference labs, digital-health startups, and EHR vendors across the US. For specific mobile use cases, our mobile FHIR integration service covers iOS and Android patient-access apps end-to-end. And for Mirth-based FHIR adapters, see our Mirth FHIR Server offering.

Common engagement shapes:

• Certification sprint — 4–8 week engagement focused on ONC certification.
• FHIR façade build — 6–12 weeks to stand up FHIR in front of an existing v2 environment.
• SMART app build — 4–10 weeks for a production-ready SMART on FHIR app.
• Managed FHIR operations — ongoing 24/7 support for production FHIR endpoints via our Mirth helpdesk.

16. Frequently Asked Questions

Related Reading

• Mirth Connect: The Complete Guide
• HL7 Integration: The Complete Guide
• FHIR Integration Services
• FHIR Development Solutions
• Mirth FHIR Server
• Mobile FHIR Integration
• FHIR Adoption Is Surging: What 2025 Data Tells Us
• Mirth Connect + FHIR: Powering the Next Generation of Healthcare Data Exchange
• Healthcare Software Product Development with Mirth & FHIR