Written by Technical Team | Last updated 15.08.2025 | 24 minute read
Epic’s implementation of FHIR exposes a consistent, standards-based façade over a complex electronic health record. For developers, that façade lives at open.epic.com, where you’ll find the documentation, test sandboxes, and registration flows you’ll need to bring a SMART-on-FHIR app to life. The promise is simple: authenticate securely, request a well-defined set of clinical and administrative resources, and receive structured JSON conforming to FHIR profiles. In practice, the experience is shaped as much by Epic’s operational realities—versioning, deployment patterns, and organisational governance—as by the FHIR standard itself.
At its core, Epic supports the SMART on FHIR launch framework and FHIR RESTful interactions across a defined set of resources. You will encounter the familiar HTTP verbs—GET for reads, POST for creates, PUT/PATCH for updates where permitted—and the standard FHIR search parameters like _id, identifier, name, date, and patient. The big picture is that patient-centric workflows are prioritised: reading a patient’s demographics, problems, medications, allergies, observations and encounters is straightforward, while cross-patient queries and bulk exports are tightly controlled or reserved for back-office integrations negotiated with each healthcare organisation.
Crucially, Epic’s FHIR surfaces are not monolithic. Each customer (a hospital or integrated care system) runs its own Epic instance with its own FHIR endpoints, scopes, and release cadence. The open.epic.com sandbox behaves like a reference implementation and is invaluable for development, but production connectivity involves onboarding with each organisation you wish to serve. As a result, portability is excellent at the code level but operational integration still demands relationship management, app reviews, and environment-specific configuration.
Finally, Epic’s resource coverage and search behaviours are extensive but opinionated. You will find R4 widely available, with R5 emerging in places, and a catalogue of Epic-specific profiles and extensions that add clinically useful nuance. The value for developers lies in learning those profiles and the patterns that Epic encourages—well-scoped searches, careful pagination, and defensive parsing of optional fields—so that your app behaves predictably across organisations and upgrade cycles.
A successful Epic on FHIR integration starts with a precise understanding of identity flows. SMART on FHIR builds on OAuth 2.0 and OpenID Connect, using an authorisation code flow (with PKCE in native and public clients) to obtain access tokens. These tokens encode scopes that define which FHIR resources you may read or write, and at what granularity. In patient-facing contexts (for example, launching from MyChart or from an Epic-hosted patient portal), scopes are typically limited to a single patient’s data. In clinician-facing contexts (for example, launching inside the Epic clinician workspace), scopes may be broader but still bound by strict policy and audit constraints.
Scopes are both familiar and subtly different. You’ll see standard SMART scopes like openid, profile, and offline_access, alongside resource-specific scopes such as patient/Observation.read or user/MedicationRequest.write. The patient/ prefix binds the scope to the patient in context; user/ indicates permissions based on the current authenticated user; and system/ scopes—when available—enable non-interactive server-to-server interactions. Understanding the minimal scope set your app truly needs is not just a security best practice; it’s also a practical necessity, because organisations will scrutinise your requested scopes during security review and may decline overly broad requests.
Registration at open.epic.com is the entry point. You create an app record, declare your redirect URIs, and select the launch and scope patterns your app requires. The sandbox offers both standalone and EHR-launch scenarios so you can test the full redirect and token exchange flows. It’s wise to treat that app record as a “template”: in production you will often create environment-specific app entries with organisation-provided credentials, and you should be ready to map those configurations into your deployment pipeline without changing code.
Token hygiene and key management are non-negotiable. Even if you build a JavaScript SPA or a mobile app with PKCE, you’ll still want a backend component for exchanging codes, storing refresh tokens securely when permitted, and brokering calls to the FHIR API to avoid exposing sensitive endpoints directly to browsers. Refresh tokens may be time-limited or disallowed depending on the organisation, so your client must gracefully handle token expiry and re-authentication. Incorporate clock skew tolerance, robust handling of WWW-Authenticate headers, and a clean content-security policy to keep redirects and token exchanges safe.
Lastly, accept that “identity” means more than OAuth. Epic environments carry their own user directories, patient identifiers, and organisation-specific extensions. You will meet multiple identifiers for the same patient (MRN, NHS number, local IDs), and you’ll need a resolute strategy for mapping those IDs without creating patient-matching risks. Build your data layer to treat identifiers as first-class and to store the system URI along with each identifier so you can reason about provenance later.
The quickest route from idea to working integration is a disciplined, end-to-end path that you can rehearse in the open.epic.com sandbox and then repeat for each production organisation. Think of the journey in three arcs: designing the user journey, implementing the SMART handshake, and proving your data queries behave well under real-world constraints.
Start with the user journey because it determines your launch context. A clinician-launched app presents with a patient and possibly an encounter already in context; you inherit that context through id token claims and launch parameters, which simplifies your first FHIR calls. A standalone app must discover its patient via search or patient authorisation, and that discovery flow deserves particular care: patients may not know their identifiers, and consent screens should be written plainly to avoid confusion. In both cases, clarity around what your app will do with the data—and how the user exits back to Epic—reduces friction during security review.
From there, implement the authorisation code flow rigorously. Construct your authorisation request with exact redirect URIs, a cryptographically strong state parameter, and PKCE values where required. Once redirected back, exchange the code for tokens at the token endpoint, validate the id token (including issuer, audience, and nonce), and bind the session to your server-side notion of user and patient. Store only what you need; log everything you must. Access tokens are short-lived by design, so your code should treat them as consumables rather than durable credentials.
Finally, wire up your first FHIR calls. The most common opening trio is Patient, Encounter, and Observation, because together they tell you who, where, and what clinically meaningful data exists to display. Requests should include a sensible _count to control page size, a stable sort where available (for example, date or -date), and if you’re presenting time-series data, a windowed search to keep response payloads small. Your UI must be resilient to optionality: not every patient has structured allergies; not every observation has a valueQuantity; and not every medication has a structured dosageInstruction. Defensive rendering that treats missing fields as normal makes your app feel fast and considered rather than fragile.
Map out your integration steps as a repeatable checklist:
Test edge cases: patients with no allergies, very large medication lists, or multiple concurrent encounters.
FHIR’s elegance lies in its consistency, but clinical data is intrinsically messy. Epic’s FHIR endpoints hew to the specification while embracing practical extensions to capture nuance. As you design your data layer, model three categories: canonical fields you can rely on across implementations; optional fields that you should surface when present; and extensions that you persist and report but rarely normalise. This approach guards you against “false certainty” where you assume a field will exist or mean the same thing everywhere.
Terminology deserves particular attention. Observations may carry units in UCUM; problems and diagnoses in SNOMED CT; medications by RxNorm or local formulary codes; procedures in SNOMED or CPT depending on jurisdiction; and organisations by ODS/HES or other national systems. Your equality checks must therefore privilege the coding system URI first, then code, then display. A robust coding helper that can resolve concepts across systems (or at least present them intelligibly) is invaluable, especially when you aggregate data from multiple sites or countries.
Performance is not just about speed; it’s about predictability. Set a default page size that yields fast first paints, usually between 20 and 50 resources depending on payload weight, and design your UI to stream in subsequent pages as the user scrolls. Where supported, constrain queries by date range to avoid reading years of historical data when you only need the last 90 days. Prefer server-side sorting when the API offers it; otherwise, define client-side fallbacks that are stable and documented. If you show longitudinal graphs—vital signs, lab trends—consider caching by resource ID and meta.lastUpdated so you can reconcile changes without reloading the entire series.
You should also cultivate healthy scepticism about completeness. Not every clinically relevant concept maps neatly to a single FHIR resource, and not every datum that exists in the EHR is exposed via FHIR. For example, documents (as DocumentReference) may be abundant but unstructured; flowsheets may render as Observation groups with linked components; and complex medication instructions can require careful parsing of timing, dose, route, and PRN logic. The safe default is to present what you know clearly, show provenance prominently, and avoid implying a negative (“no allergies”) when your scope only allows you to say “no allergies recorded”.
Technical readiness is necessary but not sufficient for a successful Epic integration. The path to production usually involves organisational governance, privacy reviews, and demonstration of clinical safety. Healthcare organisations are rightly cautious about data flows, and your app will be assessed not just for security but also for clinical clarity, usability, and supportability. This is where documentation and operational maturity count: articulate your threat model, enumerate your data flows, and show you can triage and resolve issues quickly.
Expect to produce a straightforward bundle of artefacts for review: a data protection impact assessment or equivalent, an information security questionnaire aligned to recognised frameworks, and a user-facing privacy notice that explains what you store, for how long, and why. You’ll also be asked how you handle consent, especially for patient-facing apps. Consent must be explicit, revocable, and logged; your user interface should let patients see and manage connected organisations and revoke access cleanly. Where your app performs decision support, have a clear statement of intent and limits so clinicians understand what your tool does and does not do.
Operationally, you succeed in production by taking configuration seriously. Each Epic customer will provide connection details—issuer URLs, authorise/token endpoints, JWKS URIs, and sometimes custom parameters—along with environment labels (Dev, Test, Training, Production). Build your deployment pipeline so that new organisations can be onboarded by configuration alone. Maintain a registry of endpoints, keys, and scopes with access controls, audit trails, and secrets rotation policies. Monitor token exchanges and API call success rates so you can detect and resolve issues before users notice.
A pragmatic “go-live” checklist helps align teams and reduce risk:
Moving beyond first go-live, treat your integration as a living system. Epic instances upgrade periodically; scopes and resource support can expand; and regulatory frameworks evolve. Keep a regular cadence of sandbox regression tests, monitor deprecation notices, and rehearse token and key rotations. Build a habit of communicating changes with your customer organisations ahead of time, particularly when your app behaviour or required scopes change. In healthcare, predictability and transparency are as valuable as features.
Clinician-facing integrations shine when they respect context and time. If a launch occurs within the electronic health record, your app will often receive patient and encounter information that sets the stage for immediate value. Design your first screen to use that context without asking clinicians to search or click through unnecessary steps. Summaries should be crisp and actionable: a short problem list, recent medications, the latest vital signs or key labs, and any alerts that require attention. When a deeper dive is needed, your navigation should let the user drill down by category or timeline without losing sight of the clinical question at hand.
Trust comes from provenance and explainability. Show where and when the data came from (meta.lastUpdated and organisation names), and surface coding details when they matter (for example, units and reference ranges for labs). If your app calculates scores or recommendations, include brief “how this was calculated” links that open contextual help. Avoid dark patterns: make it obvious when you are pulling fresh data versus showing something cached, and never hide delays or errors. A clinician’s mental model of your tool should be one of dependable, honest assistance.
Patient experiences require different choices. Patients often have fragmented records, varied levels of health literacy, and limited tolerance for jargon. Present information in plain language, cluster concepts by everyday meaning (medicines, test results, appointments), and provide educational links where appropriate. Consent screens, in particular, should prioritise clarity over cleverness: in one or two sentences, say what data you’ll access, why, and for how long; offer an explicit “no” that leaves the patient in control; and give simple instructions for disconnecting your app later.
Inevitably, there will be gaps and ambiguities. A patient may have multiple names or addresses recorded, a medication that exists in the EHR but not in a dictionary you prefer, or a test result with an unrecognised unit. It is better to show an honest “we’re not sure” with an option to view the raw detail than to present an overconfident simplification. Your design should celebrate transparency: show the underlying codes and narrative when necessary, and invite users to report discrepancies with a clear feedback path.
The most frustrating bugs in healthcare integrations are often not bugs at all but differences of interpretation or configuration. One site may support a particular search modifier while another rejects it; one may populate a field consistently while another leaves it blank. Your error handling strategy should assume such variance and treat it as normal. Parse HTTP status codes carefully: 401 and 403 require different responses; 404 may mean “resource not found” today and “search feature not implemented” tomorrow. Read the OperationOutcome resource returned on errors—Epic provides structured details that you can convert into user-friendly messages and diagnostic logs.
Edge cases tend to cluster around identity and time. Patients who share the same name and date of birth; encounters that overlap; a journey that crosses time zones or daylight savings boundaries; and records with future-dated orders or back-dated documentation. Testing these conditions in the sandbox is useful, but you should also request test cases from each organisation that mirror their local data patterns. Your QA suite should include property-based tests that generate odd but plausible data, so you don’t rely solely on a handful of hand-crafted fixtures.
Version drift deserves deliberate attention. Even within the same FHIR version (say, R4), minor changes in profile and server configuration can alter defaults. Keep your client tolerant of unrecognised extensions and extra fields, and never hard-fail on extra JSON members. When a field is essential to your app’s logic, program defensively: validate its presence, log clearly when absent, and offer a graceful fallback in the UI. If you need to rely on a specific profile or extension, document it in your integration guide and confirm support during onboarding so there are no surprises in production.
Finally, monitor for silent failures. A token refresh that succeeds but changes the set of authorised scopes; a background process that starts returning smaller pages; a query that begins to time out during peak hours. Set up synthetic checks that run the same core searches your users depend on, and alarm not only on outright failure but also on significant shifts in latency or response size. The earlier you see a trend, the easier it is to fix before it becomes a support incident.
Privacy in healthcare is both a legal mandate and a moral duty. Your app should treat access to Epic’s FHIR data as a privilege that must be justified, documented, and minimised. Begin by articulating exactly which resources you need and why; then encode that decision into your requested scopes, your query patterns, and your data retention policies. If you don’t need a write scope, don’t request it. If you only need the last six months of lab results, don’t fetch the entire history. If a field is optional within your feature, consider not storing it at all.
Security is holistic. Encrypt data at rest and in transit, of course, but also consider how you isolate tenants if your app serves multiple organisations, how you rotate keys and secrets, and how you detect anomalous behaviour. Audit everything that touches tokens and PHI: authorisation requests, token exchanges, scope grants, data reads, and deletes. Keep logs tamper-evident and access-controlled. Where possible, design your architecture so that sensitive operations occur on servers you control, not in end-user browsers, and apply content-security policies that reduce the risk of token leakage.
Incident response is part of security, not an afterthought. Have a clear runbook for compromised credentials, unexpected data exposure, and suspected misuse. Your agreement with each organisation should describe notification timelines and mitigation actions. Rehearse this like you would a fire drill: rotate a key in a non-production environment; revoke an app’s access; simulate a log-exfiltration alert and walk through who gets paged and what they do. The confidence you build here not only protects patients; it also speeds governance approvals because you can demonstrate readiness.
Data subject rights flow naturally from good design. If a patient asks for a copy of the information you hold, you should be able to produce it quickly and completely. If they ask you to delete their data, you should be able to comply while preserving audit trails that are required for legal and operational reasons. These capabilities are easiest to implement when you have minimised what you store and when you have clear, well-indexed boundaries between PHI, operational logs, and aggregated analytics.
Raw FHIR resources are not, by themselves, clinical insight. The art of a great integration is turning structured data into helpful cues without oversimplifying or overpromising. Start by presenting the “shape” of a patient’s story: current problems, active medications, recent encounters, and pertinent results. Then layer in trends—how is the patient moving relative to their baseline or a clinically meaningful threshold? Give clinicians fast routes to the “why”: from a graph point to the underlying observation; from a medication entry to its dosing details and prescriber; from an alert to the evidence behind it.
Visualisation choices matter. Line charts for time-series vitals and labs; grouped lists for problem categories; pill-boxed layouts for active medications with strength and frequency prominent. Use conservative defaults for ranges, label axes clearly, and avoid colour-only encoding so your charts remain accessible. When you aggregate across resources—for example, calculating a risk score—expose the component values and the formula in a help panel so users can scrutinise and trust the result.
Decision support sits atop this foundation. Whether you implement guidelines, reminders, or predictions, tie each suggestion to patient-specific data you can cite and, where applicable, give the user a one-click path to the relevant sections of the record. Keep support “assistive” rather than “prescriptive” unless you have explicit clinical governance for automated actions. Capture outcomes feedback where possible: did the user accept or dismiss a recommendation, and why? These feedback loops improve your models and demonstrate utility to your partner organisations.
Remember the diversity of clinical practice. The same data can mean different things in emergency medicine, oncology, or primary care. Design your app so it can adapt content and emphasis to the clinical context—either by detecting the launch location or by allowing users to choose a working mode. Lightweight customisation (for example, which labs to show first) can have outsized impact on perceived usefulness and adoption.
Testing a healthcare integration is a marathon, not a sprint. Unit tests validate your token logic and parsers; integration tests confirm you can talk to a FHIR server; but it’s system tests that prove clinical readiness. Use the sandbox to create scenario-based scripts: a new patient admission, a chronic condition review, a medication reconciliation visit. Seed data that exercises branching logic—missing values, uncommon codes, multi-component observations—and assert that the UI stays stable and helpful.
Telemetry turns production into a learning system. Instrument your authorise/token flow, initial data fetches, and key UI actions. Track latencies, page counts, failure rates, and the distribution of resource types. Watch for outliers: a sudden rise in 429 responses may indicate unannounced rate limiting; a drop in average payload size could point to a change in default search parameters. Share anonymised performance summaries with your partner organisations—they appreciate visibility, and it builds trust when you can show how you detect and resolve issues proactively.
Cross-organisation variance is inevitable, so embrace configuration as code. Keep organisation-specific details in declarative manifests—endpoints, scopes, feature flags, page sizes—and version them alongside application code. A new organisation should be an addition to a registry, not a bespoke branch. When you discover an environment that behaves differently—say, it requires a slightly different search parameter—aim to add a feature flag and a test rather than a one-off fork.
Feedback loops close the improvement cycle. Provide an in-app “Send feedback” channel that captures context automatically (resource IDs, timestamps, request IDs stripped of PHI). Hold regular reviews with clinical champions at each organisation and turn their suggestions into small, frequent releases rather than occasional big bangs. Incremental improvement is friendlier to governance and easier on users, who can absorb change in digestible pieces.
FHIR REST APIs are the day-to-day workhorse, but some use cases need different integration patterns. Bulk data export (the Flat FHIR or $export pattern) enables population-scale analytics by delivering NDJSON files in batches. This is typically a governed, back-office capability: you negotiate the scope, schedule, and delivery mechanism with each organisation, and you build a pipeline that can ingest and process large files safely and efficiently. The trade-off is latency: bulk delivers breadth, not immediacy.
Event-driven patterns are the flip side. Subscriptions and webhooks can notify your app when relevant changes occur—new observations, updated medications, admissions and discharges—so you don’t have to poll constantly. When available, they allow near-real-time features while respecting rate limits and server load. The design challenge here is idempotency: your handlers must tolerate duplicate events and out-of-order delivery, and your data model must reconcile state changes deterministically.
Hybrid patterns are common in mature deployments. You might use REST for interactive reads, a subscription for alerts, and bulk exports for nightly analytics. The key is to keep boundaries clear and to ensure that identifiers and provenance travel consistently across channels. If a patient’s lab result arrives via subscription before it’s available to the REST search you use to build your UI, your app should handle that gracefully—perhaps by highlighting that a new result is pending verification or by reconciling the two sources once REST catches up.
As you explore these patterns, keep your governance and consent model consistent. If consent covers interactive reads but not analytics, your pipelines must enforce that distinction technically, not just contractually. The best time to encode those rules is early, in the architecture, rather than later, in policy documents that drift from reality.
Beyond correctness and safety, a successful integration must be economical—for you and for the organisations that host the EHR. Rate limits exist to protect system stability. Some are explicit (requests per minute per client), others implicit (query complexity that degrades performance). Your code should measure and adapt: exponential back-off on 429 responses, a queue that coalesces duplicate queries, and user interfaces that communicate when large searches will take time.
Caching offers major wins when used carefully. Cache immutable resources aggressively—metadata, capability statements, and static code systems. For patient data, consider conditional requests using If-None-Match or If-Modified-Since where supported, and reconcile responses with local caches using resource IDs and meta.versionId. The hazards are stale data and privacy; don’t cache beyond what your consent model allows, and always make it obvious when the screen shows cached information rather than a fresh read.
Think about cost across your whole stack. Serverless functions can make your SMART token exchange both scalable and auditable; containerised services let you version and roll back easily; message queues buffer load spikes and isolate UI performance from temporary FHIR slowness. The end goal is not to squeeze every last millisecond, but to create a system that feels fast to users, behaves politely to Epic’s servers, and stays simple enough to operate confidently.
Finally, measure the impact of architectural choices on clinical flow. A page that renders in 300 ms but triggers a background flurry of unnecessary calls is not sustainable. A design that fetches only what’s needed for the current view, prefetches the next likely resource, and reuses recent results will feel just as fast and will scale much further. When you hit limits, talk with your partner organisation; sometimes a small change in query pattern or an agreed subscription transforms performance.
The through-line of a great Epic on FHIR integration is discipline. You build against the standard, in the sandbox, with minimal scopes and careful parsing. You carry that discipline into production by treating each organisation’s environment as configuration, by monitoring your flows, and by communicating openly when things change. You earn clinicians’ trust with clarity and context; you earn patients’ trust with control and candour; and you earn security teams’ trust with sound engineering and measured scope.
A pragmatic blueprint looks like this in action. You begin by registering a sandbox app at open.epic.com, setting precise redirect URIs, and selecting only the scopes you need. You implement the SMART launch flows with PKCE, careful validation, and clean session boundaries. You write a data layer that respects pagination, understands clinical coding systems, and tolerates missing fields. Your UI tells a coherent clinical story, defers to provenance, and makes it easy to dive deeper without getting lost. You exercise the app against synthetic edge cases and then with organisation-provided test accounts, tighten the loops where you see friction, and prepare your governance pack.
As you onboard organisations, you create environment-specific configurations, rotate credentials regularly, and document search patterns and expectations so everyone knows what “good” looks like. You set up telemetry that watches token exchanges, endpoint health, and end-user journeys, and you build synthetic checks that warn you when behaviour drifts. You treat errors as signals and version differences as normal, not as exceptions. You iterate in small, safe steps that respect clinical workflows and never surprise users.
When you’re ready to scale, keep three guiding habits:
In the end, “Epic on FHIR” is less a single product and more a contract between standards, platforms, and people. The standards provide a shared language; Epic’s platform offers a powerful doorway into rich clinical data; and your team brings the craft that turns that access into real value for clinicians and patients. With a careful approach to identity, data handling, and operational excellence, you can build integrations that are not only compliant and portable, but also delightful to use and resilient in the messy, vital world of healthcare.
Is your team looking for help with Epic integration? Click the button below.
Get in touch