How to Connect Your App to Epic EHR Using FHIR APIs

If you are building a healthcare app for the US market, there is a good chance you will eventually run into Epic. Epic powers over 35% of US hospital EHR systems, making it one of the most important healthcare platforms for interoperability and third-party integrations.

Not “maybe”. More like “inevitably”.

Epic is one of the most widely used healthcare systems in the United States, and when clients ask for integration, they usually mean Epic.

So the real question is not whether you can integrate with it. It is how to do it properly without getting stuck in sandbox issues, scope rejections, token errors, or App Orchard delays that can easily stretch for weeks.

Let’s break it down in a practical way that actually reflects how Epic integrations work in real engineering environments.

How Epic EHR FHIR APIs Actually Work

Epic exposes clinical data through FHIR R4 APIs. These are REST based APIs that return structured healthcare data such as patients, lab results, medications, encounters, and diagnostic reports.

On paper, it looks simple. You call an endpoint and get JSON back.

In reality, there is a controlled security layer sitting on top of everything.

Epic uses SMART on FHIR, which is an OAuth2 based authorization framework designed specifically for healthcare systems. It is not just authentication. It controls three things at once:

• User identity
• Application permissions
• Patient context

This is where most developers get confused in the beginning.

You are not just calling an API. You are operating inside a secured EHR session that Epic controls.

So instead of a normal API flow like “request → response”, Epic works more like:

1. Your app is launched inside Epic
2. Epic passes context parameters
3. User is authenticated in Epic session
4. Your app receives scoped access
5. Then API calls are allowed

There are two environments you will work with.

Sandbox at open.epic.com is used for development and testing. This is where you experiment freely with test patients.

Production access comes through Epic App Orchard, and this requires approval, documentation, and security review.

A real Epic FHIR endpoint looks like:

GET https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/Patient/{id}

The same pattern applies across most resources like Observation, Condition, MedicationRequest, and Appointment.

At scale, this consistency is what makes FHIR powerful, even though the onboarding process is strict.

Step 1 Getting Sandbox Access

The first real step is getting access to Epic’s sandbox environment.

You go to https://open.epic.com and create a developer account. The process is straightforward and does not require approval.

Once you are inside, Epic provides a full development setup that includes:

• Test patient records
• FHIR R4 endpoints
• Sample SMART applications
• Prebuilt API collections for tools like Postman

This is the environment where most developers understand how Epic actually behaves under real API calls.

For example, you can immediately try fetching a patient record:

GET https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/Patient/erXuFYUfucBZaryVksYEcMg3

A typical response looks like this:

{
  "resourceType": "Patient",
  "id": "erXuFYUfucBZaryVksYEcMg3",
  "name": [
    {
      "family": "Smith",
      "given": [
        "John"
      ]
    }
  ],
  "gender": "male",
  "birthDate": "1980-05-12"
}

At this stage, your goal is not complexity. You are just validating connectivity, authentication, and response structure.

Most developers underestimate this phase, but it is where you confirm whether your system can reliably talk to Epic at all.

Step 2 Registering Your App

Once sandbox testing works, the next step is registering your application in Epic App Orchard.

App Orchard is Epic’s controlled ecosystem for third party integrations. Nothing goes to production without passing through it.

During registration, you define your application metadata:

• App type such as patient facing or clinician facing
• Redirect URIs for OAuth callbacks
• FHIR scopes your app needs
• Basic product description and workflow

After review, Epic issues a client ID that becomes your application identity inside their system.

Scopes are one of the most important parts of this step.

They define exactly what your application can access.

For example:

• patient/Patient.read allows demographic access
• patient/Observation.read allows lab and vitals data
• user/MedicationRequest.read allows clinician level medication access

A common mistake is over-requesting scopes.

Epic reviewers actively reject applications that request broad permissions without justification. In healthcare systems, least privilege is not optional. It is enforced.

So your scope design should reflect real product behavior, not future assumptions.

Step 3 SMART on FHIR Authentication

This is the core of Epic integration.

SMART on FHIR is an OAuth2 based authentication system, but with healthcare specific enhancements.

It handles login, authorization, patient context, and token issuance.

Here is the actual flow in practice.

Your application is launched inside Epic. Epic passes two important parameters: launch and iss.

Your backend uses these to start an OAuth authorization flow. The user then logs in through Epic and approves access.

After approval, Epic returns an authorization code.

That code is exchanged for an access token.

Token exchange example:

POST https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
code=AUTH_CODE
redirect_uri=YOUR_REDIRECT_URI
client_id=YOUR_CLIENT_ID

Response:

{
  "access_token": "eyJhbGciOi...",
  "patient": "erXuFYUfucBZaryVksYEcMg3",
  "scope": "patient/Patient.read patient/Observation.read",
  "expires_in": 3600
}

Once you receive this token, it becomes your gateway to all FHIR APIs.

But this is also where many systems break in production.

Common issues include missing launch context, incorrect redirect URI matching, and poor token lifecycle handling.

Tokens must always be stored securely on the backend. Never expose them in frontend storage or client side logs.

You also need to design for expiration because Epic tokens are time limited and require re-authentication flows.

Step 4 Query FHIR Resources

Once authentication is stable, you can start querying real clinical data.

Most Epic integrations revolve around a small set of FHIR resources:

• Patient for demographics
• Observation for labs and vitals
• Condition for diagnoses
• MedicationRequest for prescriptions
• Appointment for scheduling
• DiagnosticReport for clinical summaries

Example queries:

GET /Observation?patient={id}
GET /Condition?patient={id}
GET /MedicationRequest?patient={id}

Responses come back in FHIR Bundle format, which is essentially a paginated container of resources.

Example:

{
  "resourceType": "Bundle",
  "link": [
    {
      "relation": "next",
      "url": "https://fhir.epic.com/.../next-page"
    }
  ]
}

Pagination is critical. If you do not implement it correctly, your application will silently miss large portions of patient data.

Another important detail is that Epic sometimes includes extensions that are not part of base FHIR R4. Your system should not assume strict schema validation or it may break unexpectedly.

Step 5 Moving to Production

Once your integration works in sandbox, the final step is production approval through Epic App Orchard.

This is where Epic evaluates your application for real world usage.

They review your:

• Security architecture
• OAuth implementation
• Scope justification
• Redirect URI configuration
• Privacy and data handling policies

The review process typically takes four to eight weeks depending on complexity.

Most delays happen not because of technical failures but because of incomplete or unclear documentation.

To improve approval speed, your submission should clearly explain:

• What your app does
• Why each scope is required
• How data is handled securely
• How authentication flows are implemented

Think of this step as a product review, not a technical checkbox.

FAQs

Conclusion

Epic integration becomes much easier once you understand the structure behind it.

1. Sandbox first for learning
2. App registration for identity
3. SMART on FHIR for authentication
4. FHIR APIs for data access
5. App Orchard for production approval

Each step builds on the previous one.

FHIR defines how data is structured. SMART on FHIR defines how access is controlled. Epic defines the operational boundaries.

Once this mental model is clear, integration stops feeling unpredictable and becomes a repeatable engineering process.

At Aishco Solutions, we help healthcare organizations and software teams successfully implement Epic FHIR integrations, SMART on FHIR authentication, and App Orchard approval strategies to build secure, scalable, and production-ready healthcare applications.

Real-world Epic integration depends more on long-term maintainability than initial setup. Modular FHIR clients, secure auth layers, and strong logging are essential. Continuous alignment with Epic updates and FHIR changes ensures stability, scalability, and compliance in production environments. Proper testing across sandbox and production further reduces integration risks and improves reliability over time, especially under heavy clinical workloads and peak usage scenarios.