The Epic FHIR API, in Practice.
FHIR R4 and US Core, the resources Epic actually exposes, reading vs writing, the endpoint pattern, and where the gaps are (yes, Bulk Data has one). A working engineer's map of the Epic FHIR API — not a spec dump.
What the Epic FHIR API Actually Is
Epic exposes a large, standards-based FHIR API — hundreds of resource endpoints, documented per version on fhir.epic.com and catalogued on open.epic.com. It's how modern apps read and write the chart without proprietary hooks, and it's the same API that Epic's certified US Core support is built on. If you're integrating a product with Epic, this is the surface you'll spend most of your time in.
Two things trip people up. First, Epic runs three FHIR versions at once — DSTU2, STU3, and R4 — with R4 recommended for anything new. Second, the API is read-heavy: reads and searches are broad and well-supported, while writes are enabled per resource and get more scrutiny. Below, we map the resources you'll use, the version story, the request pattern, and the one Bulk Data gap worth knowing before you architect around it.
The US Core Resources Epic Exposes
The resources you'll actually query, grouped by domain — with whether they're read-only or support writes. Pick a category.
Demographics, identifiers, contacts — the anchor every other query hangs off.
Problems and diagnoses (problem list, encounter diagnoses), SNOMED / ICD coded.
Vitals, labs, smoking status, social history — LOINC coded. Writable for many flows (e.g. RPM vitals).
Allergies and intolerances with reactions and criticality.
Vaccination history, CVX coded — common for registries and patient apps.
Performed procedures and surgical history.
Orders and prescriptions (active meds), RxNorm coded — the core meds resource.
Reported/reconciled medications the patient is taking.
Inpatient administration events — what was actually given, and when.
The drug definitions referenced by the resources above.
Lab and imaging reports — grouped results with interpretations.
Clinical notes and documents. Writable — the standard path to push a note or PDF into the chart.
The raw content (PDF, CDA, image) referenced by a DocumentReference.
Radiology study metadata (DICOM series/instances) for imaging workflows.
Individual lab results, LOINC coded, that make up a DiagnosticReport.
Visits and admissions — the context most clinical data is scoped to.
Scheduling — read slots and, in supported flows, book/update appointments.
Insurance/coverage details for eligibility and RCM-adjacent workflows.
Care management context — plans, the team, and patient goals.
Orders and referrals — the request side of referral loops.
The directory resources that other records reference.
Illustrative of Epic's US Core FHIR surface — exact resources, versions, and write support vary by Epic release and each customer's configuration. Confirm the live capability statement per environment. Read/write labels are general guidance.
DSTU2, STU3 and R4 — All at Once
Epic documents the same resources separately for each FHIR version. Build on R4 unless you have a specific reason not to.
Use This
The most complete, US Core-aligned surface. Epic's SMART cards and new development target R4. The R4 read layer even splits Patient Chart vs Outside Record data.
Legacy
Still documented and supported, but superseded by R4 for new work. You'll mostly encounter it in older integrations.
Oldest
The earliest generation, kept for backward compatibility. Migrate off it — and note this is where Epic and Oracle Health differ (Oracle Health retired DSTU2 in Dec 2025).
How You Actually Query Epic FHIR
Every Epic customer runs its own FHIR base URL (Epic is federated). Once you have a token, the calls are standard REST.
# Base URL is per-customer (no single Epic endpoint) — e.g.{fhir-base} = https://fhir.{customer}.org/api/FHIR/R4# Read one resource by idGET {fhir-base}/Patient/{id}# Search — Observations for a patient, filtered by categoryGET {fhir-base}/Observation?patient={id}&category=laboratory# Write — push a document into the chart (where enabled)POST {fhir-base}/DocumentReferenceAuthorization: Bearer {token}Content-Type: application/fhir+json{ "resourceType": "DocumentReference", ... }
Illustrative. Because the base URL is per-customer, a big part of real Epic work is managing endpoints and tokens across many customers — which is what our onboarding layer standardizes.
FHIR Bulk Data, and the _since Gap
For population-scale data, Epic supports FHIR Bulk Data — the asynchronous $export operation that returns large sets of resources as ndjson, authorized via SMART Backend Services. It's the right tool for analytics, warehousing, and cohort pulls where per-patient calls won't scale.
The gap worth knowing up front: Epic does not support the _since incremental filter on Bulk export (as of recent guidance) — the parameter that lets you pull only resources changed since a timestamp. Practically, that means you re-export the full set rather than a delta, which affects how you design refresh schedules and storage. Oracle Health and eClinicalWorks do support _since, so if incremental bulk is core to your product, design for the difference per vendor.
Where Epic FHIR API Work Goes Wrong
The mistakes we're most often called in to fix.
Reads are broad; writes are enabled per resource and per customer. Confirm the resource is writable before you design a write-back flow.
Older tutorials target DSTU2/STU3. New builds should be R4 — you'll get the most complete, US Core-aligned surface and avoid a migration later.
_since bulk deltasEpic doesn't support incremental Bulk export — architect for full $export cadence or change-detection, not a delta that isn't there.
Epic is federated — every customer has its own FHIR base URL. Build endpoint + token management for many customers from day one.
Epic FHIR API, Answered
The questions engineers ask before building against it.
Which FHIR Version Should I Use with Epic?
Can I Write Data Back to Epic with FHIR?
Observation (e.g. RPM vitals), DocumentReference (notes/documents), and scheduling. Because writes attract more security scrutiny, we scope them tightly to exactly what your workflow needs.What FHIR Resources Does Epic Support?
Patient, Encounter, Condition, Observation, AllergyIntolerance, Immunization, Procedure, MedicationRequest, DiagnosticReport, DocumentReference, ServiceRequest, Appointment, Coverage, care-management and directory resources, and others. The exact list depends on the Epic release and each customer's configuration — always check the live capability statement.Does Epic Support FHIR Bulk Data and the _since Filter?
$export) via SMART Backend Services for population-scale pulls. However, it does not support the _since incremental filter (as of recent guidance), so you re-export full sets rather than deltas. Oracle Health and eClinicalWorks do support _since — plan your refresh strategy per vendor.Is There One Epic FHIR Endpoint?
How Is the Epic FHIR API Authorized?
More on Epic Integration
Epic Integration, End to End →
The full ecosystem, programs, Vendor Services, Showroom, and the vendor journey.
Build a SMART App for Epic →
Launch types, the OAuth flow, scopes, and app registration.
What Epic Integration Costs →
Ranges by scenario, what drives them, and how to reduce them.
Tell Us Which Resources You Need.
Book a scoping call — we'll map the exact FHIR resources, reads vs writes, and endpoint/token strategy for your Epic build. Reviewed by an integration engineer, not a sales queue.
Thanks — We've Got It.
A Nirmitee integration engineer will reach out within one business day.