FHIR API integration: a practical guide for connecting to Epic and modern EHR systems.

FHIR — Fast Healthcare Interoperability Resources — is a data standard published by HL7 International. It defines a set of modular resources (Patient, Encounter, Observation, MedicationRequest, and many more) and a RESTful API for reading and writing them over HTTP using JSON.

In practical terms, a FHIR API looks like any other modern REST API. You issue an authenticated GET to a URL like /Patient/123 or /Observation?patient=123&category=vital-signs and receive back a JSON document you can render in a web or mobile app. That familiarity is the entire point: FHIR was designed to make clinical data reachable by developers who have never touched HL7 v2 or CDA.

The current widely supported version is FHIR R4, with R5 available and R6 in development. Most major EHR vendors — Epic, Cerner (Oracle Health), Meditech, Athenahealth, Allscripts, and others — expose FHIR R4 endpoints today, and the US Core implementation guide profiles those resources for the United States regulatory environment.

For a decade, integrating with healthcare systems meant HL7 v2 interfaces, VPN tunnels, and per-site engineering effort measured in months. FHIR does not eliminate the operational work, but it changes the technical baseline in three important ways:

• Ubiquity. The 21st Century Cures Act and the ONC Cures Act Final Rule require certified EHRs to expose standardized FHIR APIs. If a US hospital runs a certified EHR, a FHIR endpoint exists.
• Familiar tooling. REST, JSON, and OAuth 2.0 are already part of every modern stack. Your team can read a FHIR response with the same tools they use for Stripe or GitHub.
• App-centric model. SMART on FHIR defines how third-party apps launch from within an EHR, receive patient context, and request scoped access — a workflow that simply did not exist in the HL7 v2 world.

The result: capabilities that used to require six-figure integration engagements — patient-facing portals, provider tools that read live chart data, remote-monitoring pipelines — are now achievable by a focused product team with the right architecture.

Resources

Everything in FHIR is a resource: a self-describing JSON object with a stable resourceType, an id, and a set of typed fields. Resources reference each other by ID (an Observation references a Patient), forming a graph you can traverse with standard REST calls or with FHIR's _include and _revinclude parameters.

Interactions

FHIR defines a small vocabulary of interactions on top of HTTP: read, vread, update, patch, delete, create, search, history, and capabilities. Bundles let you batch multiple interactions into a single request, and transactions guarantee atomicity when a vendor supports them.

Profiles

The base FHIR spec is deliberately flexible. Profiles constrain it for a specific use case — US Core for US clinical data, CARIN Blue Button for payer data, International Patient Summary for cross-border exchange. When integrating with a specific EHR, check which profiles it supports; that determines which fields you can rely on being populated.

Search

FHIR search is expressive: you can filter by codes, date ranges, references, and chained parameters. Example: GET /Observation?patient=123&code=http://loinc.org|8480-6&date=ge2024-01-01 returns systolic blood pressure readings for a patient since the start of 2024.

• Patient — demographics and identifiers.
• Practitioner / PractitionerRole — clinicians and their roles at organizations.
• Encounter — a visit or interaction (inpatient stay, office visit, telehealth session).
• Observation — vitals, lab results, screening scores, remote monitoring data.
• Condition — diagnoses and problem-list entries.
• MedicationRequest / MedicationStatement — prescribed and reported medications.
• AllergyIntolerance — allergies and intolerances.
• DocumentReference — pointers to clinical notes, PDFs, and other documents.
• Appointment / Schedule / Slot — scheduling workflows.

Ninety percent of first integrations touch Patient, Encounter, Observation, Condition, and MedicationRequest. Start there.

SMART on FHIR is an OAuth 2.0 and OpenID Connect profile purpose-built for healthcare apps. It supports two primary launch modes:

• EHR launch. The EHR opens your app inside a clinician's session and passes a launch token. Your app exchanges that token for an access token scoped to the patient already on screen.
• Standalone launch. A patient or clinician opens your app directly, authenticates through the EHR's login, and grants scopes. Common for patient-facing apps.

Scopes are structured as patient/Observation.read, user/Appointment.write, and so on. Request only the scopes you need — health systems review scope requests during onboarding, and over-requesting delays approval.

For server-to-server integrations (population health, bulk data export), use the SMART Backend Services profile: a JWT-based client-credentials flow that lets a trusted backend authenticate without a user in the loop.

Epic exposes FHIR R4 endpoints at every customer site. Its developer program (formerly App Orchard, now delivered through Showroom and Vendor Services) is the path to production access. The typical journey:

1. Register your app in Epic's developer portal, declare the FHIR resources and scopes you need, and choose your launch modes.
2. Develop against Epic's public sandbox using synthetic patient data. The sandbox mirrors production endpoints and lets you validate SMART on FHIR flows end to end.
3. Complete Epic's technical review and security questionnaire. This covers your data handling, encryption, audit logging, incident response, and BAA posture.
4. Work with each health system that installs your app. Every customer has its own Epic instance, its own client ID, and its own go-live checklist.

Two things routinely surprise first-time integrators. First, not every FHIR resource is available at every Epic site — the available resource set depends on the customer's Epic version and modules. Second, the FHIR base URL is per-customer, so your app must support dynamic endpoint configuration rather than a single hardcoded URL.

A minimal FHIR integration has four moving parts: discovery, authorization, data access, and persistence. Here is what each looks like in practice.

1. Discover the server

Fetch /.well-known/smart-configuration from the FHIR base URL. That document lists the authorization endpoint, token endpoint, supported scopes, and PKCE requirements. Fetching /metadata returns the server's CapabilityStatement — which resources it supports, which search parameters, which interactions.

2. Handle the SMART launch

For an EHR launch, receive iss (the FHIR base URL) and launch query parameters. Build an authorization request with PKCE, redirect the user back into the EHR, and exchange the returned code for an access token, refresh token, and — for patient-context launches — a patient ID.

3. Fetch resources

Call the FHIR API with Authorization: Bearer <access_token>. Handle paging via the next link in Bundle responses, respect _count limits, and retry on 429 with the server's Retry-After header. Never assume optional fields are populated; always null-check.

4. Persist carefully

Decide up front whether you are caching, mirroring, or streaming data. Caching a Patient resource for a session is normal. Mirroring an entire EHR is a compliance and freshness problem. When you do store PHI, encrypt at rest, restrict access by role, log every read and write, and give clinicians a way to see who accessed a record.

The moment you touch identifiable patient data, you are inside the HIPAA perimeter. The technical checklist is well understood:

• TLS 1.2+ everywhere, no exceptions.
• Encryption at rest for any datastore that holds PHI, with managed keys and rotation.
• Least-privilege access controls, short-lived tokens, and MFA for administrative access.
• Audit logs that record who accessed which resource, when, and from where — retained per HIPAA guidance.
• Signed BAAs with every vendor that could touch PHI (hosting, database, logging, email, error tracking).
• A documented incident response and breach notification process before you go live, not after.

HIPAA compliance is an organizational posture, not a checkbox. SOC 2 Type II is increasingly expected by health-system procurement teams; plan for that audit path if you intend to sell into hospitals.

• Hardcoding a single FHIR base URL. Every customer has their own. Store it per tenant.
• Assuming resources are populated. Vendors and sites vary. Always defend against missing fields.
• Skipping the CapabilityStatement. It tells you what's actually supported. Use it.
• Over-requesting scopes. Slows review, spooks security teams, and rarely adds value.
• Ignoring refresh tokens. Access tokens are short-lived. Build refresh handling from day one.
• Treating the sandbox as production-equivalent. Test data is clean; real data is not. Plan for messy values, missing codes, and duplicate records.