Epic is the largest EHR vendor in the United States, deployed at health systems representing over 300 million patient records. If you're building a healthcare application that needs patient data, you'll eventually need to integrate with Epic.

Here's a practical walkthrough of accessing patient records through Epic's FHIR API; what works, what's tricky, and where the documentation doesn't tell you everything.

Understanding the Architecture

Epic's FHIR APIs are accessible through their developer program at fhir.epic.com. The platform supports both provider-facing and patient-facing applications, each with different authentication patterns and data access scopes.

For patient-directed access (what the regulations call "ONC g(10) APIs"), you'll use the OAuth 2.0 authorization framework with SMART on FHIR launch sequences. This is the pattern most health applications use when they need patients to authorize access to their own records.

The high-level flow:

1. Patient selects their healthcare provider

2. Your app redirects to the provider's authorization server

3. Patient authenticates with their patient portal credentials

4. Patient consents to data sharing

5. Your app receives tokens and retrieves data

Conceptually simple. Implementation has nuances.

Step 1: Register Your Application

Before writing any code, you need an account on Epic's developer portal (fhir.epic.com) and a registered application.

During registration, you'll specify:

• Application type: Patient-facing vs. provider-facing

• FHIR version: R4 is current; DSTU2 is legacy

• Scopes: Which FHIR resources your app needs access to

• Redirect URIs: Where authorization responses should be sent

• Authentication method: Confidential clients use client secrets or JWT; public clients use PKCE

Epic's sandbox environment includes test patients you can use during development. The sandbox test data includes patients like "Camilla Lopez" and "Derrick Lin" with populated clinical records across various resource types.

Tip: Be thoughtful about scopes during registration. Request only what you need. Broader scopes require more justification and may face longer review times when you move toward production.

Step 2: Implement the OAuth Flow

Patient-facing apps use the SMART on FHIR standalone launch sequence. Here's what that looks like:

Authorization Request

GET <https://fhir.epic.com/interconnect-fhir-oauth/oauth2/authorize>

GET <https://fhir.epic.com/interconnect-fhir-oauth/oauth2/authorize>

GET <https://fhir.epic.com/interconnect-fhir-oauth/oauth2/authorize>

The patient authenticates with their MyChart credentials and approves your data access request. Epic redirects back to your redirect URI with an authorization code.

Token Request

Exchange the authorization code for access tokens:

POST <https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token>

POST <https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token>

POST <https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token>

If you're using a confidential client, include client authentication (client_secret or signed JWT).

The token response includes:

• access_token: For API requests

• refresh_token: For obtaining new access tokens (if your app registered for offline access)

• patient: The FHIR ID of the authorized patient

• id_token: OpenID Connect identity token

Common pitfall: Token expiration varies by Epic customer deployment. Don't assume a specific lifetime; check the expires_in value and implement token refresh.

Step 3: Query Patient Data

With an access token and patient FHIR ID, you can retrieve clinical data.

Patient Demographics

Returns the Patient resource with demographics, identifiers, and contacts.

Conditions (Problem List)

Returns the patient's active and historical diagnoses.

Medications

Returns medication orders, prescriptions, and dispensing information.

Lab Results

Returns lab results with values, reference ranges, and interpretations.

Allergies

Returns documented allergies and adverse reactions.

Step 4: Handle the Real-World Complexity

The sandbox gives you clean test data. Production brings complexity.

Provider Discovery

Patients need to find their healthcare provider from your interface. Epic has thousands of customer deployments, each with their own FHIR endpoints. You'll need to maintain a directory of provider organizations and their corresponding API endpoints, or use a service that handles this mapping.

Data Variability

FHIR resources from different Epic deployments aren't identical. Field mappings vary. Extensions differ. Some deployments support resources that others don't. Your application needs to handle missing fields gracefully.

Error Handling

Epic's API returns error codes that map to specific conditions, but debugging requires understanding Epic's implementation. Common issues include:

• Token expiration (HTTP 401)

• Insufficient scope (HTTP 403)

• Patient not found or inaccessible (HTTP 404)

• Rate limiting (HTTP 429)

Log detailed error information during development. You'll need it.

Rate Limiting

Epic enforces rate limits that vary by deployment and application type. Design your application to handle throttling gracefully—implement exponential backoff and avoid burst queries.

Step 5: Move to Production

Epic's sandbox is openly accessible. Production requires additional steps:

• Your application undergoes review by Epic's app review team

• You may need to complete attestations regarding data handling practices

• Individual health system customers must approve your application for their deployment

This process takes time—plan for it in your timeline.

The Alternative: Let Someone Else Handle It

Everything above describes integrating with Epic alone. Most healthcare applications need access across multiple EHR systems: Cerner, athena, eClinicalWorks, NextGen, and others.

Each EHR has its own developer portal, registration process, OAuth implementation, and API quirks. Multiply the complexity above by the number of systems you need to support.

This is exactly the problem we solve at Consolidate Health. Our API provides patient-authorized access to clinical data across major EHR systems through a single integration point. We've already done the work of integrating with Epic and six other EHR systems.

You could spend 6-12 months building and maintaining these integrations yourself. Or you could integrate with our API in days and focus your engineering resources on what makes your product unique.

We handle the EHR complexity. You build the features your users want.