WvelabsVisit Website →
← Back to blog

FHIR API Integration: A US Guide for Health Tech Teams

October 22, 2026
FHIR API Integration: A US Guide for Health Tech Teams

A FHIR API integration connects your application to an EHR, payer system or health data platform through the standardized HL7 FHIR REST interface, instead of a custom interface built for each system. In the US, the working target is FHIR R4 with US Core profiles, secured with SMART on FHIR. Most of the effort sits in scoping, authorization, data mapping and testing against real servers, not in making the first API call.

This guide is for CTOs, VPs of Engineering and founders at fintech-adjacent, healthcare and insurance companies who need to plan an integration. It covers the standards, the regulatory calendar, an implementation sequence, and the mistakes that stretch timelines.

Wvelabs
Build a FHIR-Ready Health Product
Wve Labs designs and builds custom software, mobile apps, and web platforms, with product strategy, engineering, and AI/ML expertise.
Explore Wve Labs

TL;DR

  • Build against FHIR R4 (4.0.1), US Core and SMART on FHIR. These are the standards US regulation points to, so they are the safest base for a product that has to work across more than one system.
  • Do not assume two FHIR servers behave alike. Read each server's Capability Statement and implementation guides before you design your data model.
  • Budget time for registration, documentation review and testing with each organization. These administrative steps often take longer than the engineering.
  • Payer API deadlines under CMS-0057-F fall mostly on January 1, 2027, so payer-facing work is urgent for 2026 and 2027 roadmaps.
  • Treat security, consent and audit trails as product features from the first sprint, not a compliance pass at the end.

Table of Contents

What FHIR API integration means in practice

FHIR (Fast Healthcare Interoperability Resources) defines health data as resources such as Patient, Observation, Encounter and Coverage. A server exposes those resources over HTTP, and your app reads or writes them. The HL7 FHIR HTTP specification lists the standard interactions: read, vread, update, create and search.

If you already build REST APIs, the mechanics feel familiar. The differences matter, though:

  • A shared data model. Resources have defined fields, references and terminologies. You are mapping to a clinical model, not just JSON shapes.
  • Profiles and implementation guides. The base standard is flexible. US Core, Da Vinci and others narrow it for specific US use cases.
  • Security is a separate layer. REST does not define authentication. In practice that layer is SMART on FHIR, built on OAuth 2.0 and OpenID Connect.

HL7 FHIR also differs from the older HL7 v2 messaging many hospitals still run internally. FHIR evolved from that tradition, but it is a resource-and-API model rather than pipe-delimited event messages. Plenty of real projects need both: FHIR at the edge for your app, and a translation layer behind it for older feeds.

Why the US market is pushing FHIR R4

Two regulatory threads shape US projects.

Certified health IT and the Cures Act. ONC's certification rules require certified health IT to offer standards-based APIs using FHIR. The HTI-1 final rule overview also updated the API condition so that service base URLs, the "FHIR endpoints" your app connects to, must be published in standardized formats that better support patient-facing apps. ONC's developer roundtable material describes endpoint and organization details published as FHIR resources in a Bundle, which makes endpoint discovery less manual than it used to be.

Payer APIs under CMS-0057-F. CMS published its Interoperability and Prior Authorization final rule in January 2024. According to CMS, impacted payers must implement certain provisions by January 1, 2026, but have until primarily January 1, 2027 to meet the API requirements. The CMS fact sheet summarizes what the rule covers. If you sell to health plans or build member-facing apps, expect those payers to be standing up and testing APIs through 2026 and into 2027.

The practical consequence: more data is becoming reachable through standard interfaces, and customers will increasingly expect your product to use them. Verify the current requirements and your own obligations with counsel or a compliance specialist before committing to a regulatory claim in your product.

Why the US market is pushing FHIR R4 — overview diagram

Why standards-based integration pays off

The case for FHIR over point-to-point work is partly regulatory and partly economic. ONC's survey of digital health companies found that 73% use standards-based APIs when integrating with EHRs. The same research shows that companies connecting to multiple EHRs use standards-based APIs at far higher rates than those connecting to one system.

That pattern is easy to explain. A single custom interface can be cheaper at first. By the third or fourth customer on a different EHR, each bespoke integration carries its own testing, maintenance and support burden. If you expect to grow beyond one health system, design for the multi-system case on day one.

Why standards-based integration pays off — overview diagram

How the architecture fits together

A typical production setup has five parts.

  1. Your client app. Mobile, web or both. It never talks to clinical systems directly if you can avoid it.
  2. Your backend. It holds tokens securely, calls FHIR servers, caches where allowed, and normalizes data.
  3. An authorization flow. SMART on FHIR launches either from within the EHR (provider-facing) or standalone (patient-facing).
  4. One or more FHIR servers. EHR vendors, payer platforms or an intermediary data platform.
  5. A mapping and validation layer. It converts server responses to your internal model and rejects data that breaks your assumptions.

For mobile products, the choice of where tokens live and how refresh works is a design decision with real security consequences. We usually keep sensitive token handling on the backend and keep the device holding only a short-lived session.

Choosing an integration pattern

PatternBest forWatch out for
Direct to each EHR's FHIR APIOne or two target systems, fast pilotEach server differs; maintenance grows with every customer
Your own integration layer over multiple FHIR serversProducts that sell to many provider organizationsHigher upfront engineering, but one internal model
SMART on FHIR app launched inside the EHRClinician workflow toolsLaunch context, app approval and workflow fit
Bulk data exportPopulation health, analytics, payer reportingAsynchronous jobs, large files, strict access controls
HL7 v2 or other interface engine feeding FHIRHospitals with older internal systemsTranslation errors and data loss between models

Security and authorization

SMART on FHIR is the layer to plan around. Per the FHIR HTTP specification, security is outside what REST defines, which is why SMART's OAuth 2.0 and OpenID Connect profiles became the common solution for third-party apps.

A few design rules we apply:

  • Request the narrowest scopes your feature needs. Broad scopes slow approval and increase risk.
  • Store tokens encrypted and rotate them. Never log them.
  • Record who accessed what and when. Audit trails help during customer security reviews.
  • Plan for revocation. Patients and organizations can withdraw access, and your app must handle that cleanly.

HIPAA obligations depend on whether you are a covered entity or business associate. Have a healthcare privacy attorney or your compliance officer confirm your status and your contracts before you handle protected health information.

Some products let patients decide when and where their records go. The SMART Health Cards framework describes a signed data artifact a user can obtain from an issuer and share with a verifier, which keeps the patient in control of the exchange. In consent-heavy flows you also need a reliable way of verifying the identity of the person authorizing a release, plus a record of what they agreed to. Decide early which of these steps your product owns and which the health system owns.

Information blocking: design for easy access

The Cures Act information blocking provisions apply to health IT actors, and ONC's material shows that provider organizations are cautious about liability. Their stated aim is to make data requests simple and inexpensive for requesters, as described in ONC's provider perspective paper on APIs.

For you as a developer, this has two implications. First, a legitimate app should find documentation and registration paths on the other side. Second, if you operate data services yourself, you need clear, documented processes for responding to access requests. Ask your counsel whether your product makes you a regulated actor.

A realistic implementation sequence

1. Define the use case and the data

Write down exactly which resources you need (for example Patient, Condition, MedicationRequest, Observation, Coverage) and whether you need read, write or both. Anything you do not need is scope, review time and risk you can leave out.

2. Audit each target server

Do not assume all FHIR endpoints are equal. Pull the server's Capability Statement from its metadata endpoint. It tells you which resource types, search parameters and interactions it supports. Then compare against the implementation guides it claims, such as US Core or a Da Vinci guide.

3. Register and get credentials

Certified API developers must provide documentation and support for app registration, according to ONC. Even so, ONC's app developer and integrator perspectives report that teams run into varied documentation, organization-specific processes and testing steps. Start registration early and in parallel with development.

4. Build against a sandbox

Use vendor sandboxes and public test servers for early work. Write contract tests around the resources you consume, so a server change breaks a test rather than a customer.

5. Map, validate and normalize

Real data is messy: missing fields, local codes, inconsistent units, duplicate patients. Define what your app does when a required element is absent. Show a clear state to the user rather than failing silently.

6. Test with real organizations

Sandbox success does not guarantee production behavior. Plan a pilot with a friendly customer, with monitoring on error rates, latency and data completeness.

7. Operate and monitor

Servers get upgraded, certificates expire and rate limits change. Production FHIR integrations need alerting, versioned adapters and a clear owner. Our app and website maintenance work exists for exactly this phase.

Advanced patterns worth planning for

Basic reads and searches cover many apps. Some workflows go further:

  • CDS Hooks and coverage discovery. The Da Vinci Coverage Requirements Discovery guide describes how a server can query the client directly using the FHIR resource access mechanism from CDS Hooks when prefetch does not supply the data needed. This matters for prior authorization and payer-provider workflows.
  • Bulk data. The Da Vinci Member Attribution List guide builds on the Bulk Data implementation guide, a pattern used when moving large datasets rather than single records.
  • Provider directories. The National Directory implementation guide defines a RESTful API for the National Directory of Healthcare Providers and Services.

You may not need any of these on version one. Knowing they exist keeps your data model from blocking them later.

Common mistakes

  • Treating the first successful query as the finish line. Production readiness includes authorization, error handling, data quality and monitoring.
  • Hard-coding assumptions about one EHR. It works until the second customer.
  • Underestimating administrative time. Registration, documentation review and approval cycles often run longer than expected, even for experienced teams.
  • Skipping the Capability Statement. Teams discover missing search parameters late, after the UI is built.
  • Leaving privacy review for last. Security questionnaires from health systems can reshape your architecture.

Our perspective

We build mobile and web products for healthcare and lifestyle companies, and the pattern we see is consistent: the integration that looks like a two-week task is usually the part that defines the roadmap. The API call is simple. The hard parts are authorization UX, data normalization, and keeping the app dependable after launch.

Our advice is to prototype the user experience and the data flow together. A clean interface on top of data you cannot reliably retrieve is a demo, not a product. Designers and engineers should sit in the same room when you decide what happens on an empty record, an expired token or a patient who revokes access.

If you built a first version with an AI app builder and now need it to handle real clinical or member data, plan a hardening pass. Authentication, audit logging, error handling and a proper backend are usually the first things to rebuild, and they are the things security reviewers ask about first.

— Brian

Building your FHIR-connected product with Wve Labs

We design, build and support mobile apps, web platforms and applied AI solutions, including backend and API development, cloud deployment and ongoing product care. See our healthcare and lifestyle app development work, or review the full range on our services page. If you want to scope a FHIR integration with a team that covers design and engineering together, talk to us.

FAQ

What is a FHIR API used for?

It lets applications read and write structured health data, such as patients, observations and coverage, through a standard web interface. Common uses are patient-facing apps, clinician tools inside an EHR, payer data exchange and analytics. It replaces many custom point-to-point interfaces with one shared model.

What is the difference between FHIR and a REST API?

REST is a general architectural style. FHIR is a healthcare data standard that uses REST: it defines the resources, their structure and the interactions on them. FHIR also relies on SMART on FHIR for security, because REST itself does not define authentication.

What is the difference between HL7 and FHIR?

HL7 is the standards organization, and HL7 v2 is its older message-based standard still common inside hospitals. FHIR is the newer HL7 standard built around web APIs and resources. Many organizations run both, with translation between them.

Is FHIR API access free?

The FHIR specification is openly available. Access to a particular system depends on its owner: some offer free sandboxes and registration, while commercial platforms may charge fees or require contracts. Check each organization's developer terms, and ask your counsel about any cost rules that apply.

Sources