How to Integrate with Epic EHR: Dev Guide

Epic Systems is the dominant electronic health record platform in the United States, holding over 42% of the acute care hospital market and covering nearly 55% of US hospital beds. When you add ambulatory clinics, specialty practices, and integrated delivery networks, the reach is even broader. For healthcare app developers, medical device manufacturers, health IT vendors, and health systems building custom workflows, integrating with Epic is not optional---it is a fundamental requirement.

This guide is a technical reference for developers and integration architects who need to connect applications and systems to Epic. It covers the full spectrum of integration pathways available in 2026, from modern FHIR R4 APIs and SMART on FHIR authorization to legacy HL7 v2 interfaces that remain critical for many workflows. Whether you are building a patient-facing app, a clinical decision support tool, a population health platform, or a device integration, you will find the technical details you need here.

Epic’s Integration Architecture

Epic offers multiple integration pathways, each suited to different use cases and technical requirements. Understanding the landscape before you start building will save significant time and rework.

FHIR R4 APIs

Epic’s primary modern integration pathway. FHIR R4 APIs provide RESTful access to clinical and administrative data, conforming to the US Core Implementation Guide. This is the pathway Epic recommends for new integrations and the one that receives the most active development.

SMART on FHIR

The authorization and launch framework for FHIR-based apps. SMART on FHIR defines how apps authenticate users, obtain access tokens, and launch within the EHR context. It is built on OAuth 2.0 and is required for any app that accesses patient data through Epic’s FHIR APIs.

Epic App Market (Connection Hub)

Epic’s marketplace for third-party applications, formerly known as App Orchard. Apps listed in the App Market can be discovered and enabled by Epic customers through Connection Hub. Registration and certification through the App Market is required for apps that will be distributed to multiple Epic organizations.

HL7 v2 Interfaces (Bridges)

Epic’s legacy but still heavily used interface engine. HL7 v2 messages (ADT, ORM, ORU, SIU, MDM, etc.) flow through Epic Bridges to connect external systems. These interfaces remain essential for lab instruments, medical devices, scheduling systems, and many operational workflows.

CDS Hooks

A standards-based framework for embedding clinical decision support directly into the EHR workflow. CDS Hooks allow external services to provide real-time recommendations, alerts, and actions at specific points in the clinical workflow (e.g., when a clinician opens a patient chart or signs an order).

MyChart APIs

Patient-facing integration capabilities that extend through Epic’s MyChart patient portal. These APIs enable patient engagement features including appointment scheduling, secure messaging, health record access, and patient-reported outcomes.

FHIR R4 APIs: Deep Dive

Epic’s FHIR R4 APIs are the foundation for modern integrations. They provide RESTful access to a comprehensive set of clinical and administrative resources.

Supported FHIR Resources

Epic supports a broad set of FHIR R4 resources. The most commonly used resources for clinical integrations include:

Core Clinical Resources:

Administrative Resources:

US Core Profiles

Epic’s FHIR resources conform to the US Core Implementation Guide, which constrains base FHIR resources to meet US regulatory requirements (primarily the ONC Cures Act Final Rule and USCDI). When building your integration, always reference the US Core profile for each resource rather than the base FHIR specification. US Core profiles define:

• Required data elements (must-support elements)
• Terminology bindings (which code systems to use for coded fields)
• Required search parameters
• Cardinality constraints (which fields are required vs. optional)

For example, the US Core Patient profile requires name, gender, and identifier, and defines must-support elements for race, ethnicity, and birthDate. Your application should be prepared to handle all must-support elements even if they are not always populated.

Endpoint Discovery

Epic uses the SMART Configuration specification for endpoint discovery. To find the FHIR endpoints and authorization URLs for a specific Epic organization:

1. Start with the organization’s FHIR base URL (e.g., https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/).
2. Retrieve the SMART configuration from /.well-known/smart-configuration appended to the base URL.
3. The configuration document returns the authorization endpoint, token endpoint, supported scopes, and capabilities.

For sandbox development, Epic provides a public sandbox at https://fhir.epic.com/ where you can register a developer account and test against synthetic patient data without needing access to a production Epic environment.

Rate Limits and Best Practices

Epic enforces rate limits on FHIR API calls to protect system performance. While specific limits vary by organization and deployment, general guidelines include:

• Batch your requests. Use FHIR Bundle requests to combine multiple operations into a single API call where possible.
• Use _include and _revinclude. These search parameters allow you to retrieve related resources in a single query rather than making multiple round trips.
• Implement pagination. Large result sets are paginated. Use the next link in the Bundle response to retrieve subsequent pages.
• Cache appropriately. Use HTTP caching headers (ETag, Last-Modified) to avoid redundant requests for unchanged data.
• Respect 429 responses. If you receive an HTTP 429 (Too Many Requests) response, implement exponential backoff before retrying.

Example API Calls

Search for a patient by name and date of birth:

GET /Patient?family=Smith&given=John&birthdate=1970-01-15
Authorization: Bearer {access_token}
Accept: application/fhir+json

Retrieve lab results for a patient:

GET /Observation?patient={patient_id}&category=laboratory&date=ge2025-01-01
Authorization: Bearer {access_token}
Accept: application/fhir+json

Retrieve active medications for a patient:

GET /MedicationRequest?patient={patient_id}&status=active
Authorization: Bearer {access_token}
Accept: application/fhir+json

Retrieve a patient’s problem list:

GET /Condition?patient={patient_id}&category=problem-list-item&clinical-status=active
Authorization: Bearer {access_token}
Accept: application/fhir+json

SMART on FHIR Authentication

Every FHIR-based Epic integration requires SMART on FHIR authentication. SMART (Substitutable Medical Applications, Reusable Technologies) defines a standardized OAuth 2.0 workflow for healthcare applications. There are three primary authorization patterns.

EHR Launch

In the EHR Launch flow, your app is launched from within Epic (typically from a toolbar button, activity, or embedded iframe). Epic initiates the launch by redirecting to your app’s launch URL with a launch parameter and the FHIR server’s iss (issuer) URL.

Step-by-step flow:

1. Epic redirects to your app: https://yourapp.com/launch?iss=https://epic-fhir-server/R4&launch=abc123
2. Your app retrieves the SMART configuration from {iss}/.well-known/smart-configuration
3. Your app redirects the user to Epic’s authorization endpoint with the launch parameter, your client_id, requested scope, redirect_uri, and a state parameter for CSRF protection
4. Epic authenticates the user (if not already authenticated in the EHR session) and prompts for consent if required
5. Epic redirects back to your redirect_uri with an authorization code
6. Your app exchanges the authorization code for an access token (and optionally a refresh token) at the token endpoint
7. The token response includes the patient context (patient ID), encounter context if applicable, and the scopes that were granted

Key advantage: In an EHR Launch, the patient and encounter context are provided automatically by Epic. Your app does not need to implement a patient picker---the clinician has already selected the patient in Epic.

Standalone Launch

In the Standalone Launch flow, your app launches independently (e.g., from a bookmark, mobile app, or external portal) and must discover the patient context on its own.

Step-by-step flow:

1. Your app presents a FHIR server selection or has a preconfigured server URL
2. Your app retrieves the SMART configuration from {fhir_server}/.well-known/smart-configuration
3. Your app redirects the user to Epic’s authorization endpoint with client_id, requested scope (including launch/patient to request patient context), redirect_uri, and state
4. Epic authenticates the user and presents a patient picker (for clinician-facing apps) or uses the authenticated patient’s identity (for patient-facing apps)
5. Epic redirects back with an authorization code
6. Your app exchanges the code for an access token, which includes the selected patient’s ID

Backend Services (Client Credentials)

For server-to-server integrations that do not involve an interactive user session, Epic supports the SMART Backend Services authorization flow using the OAuth 2.0 client credentials grant.

Step-by-step flow:

1. Pre-register your application’s public key with Epic through the Connection Hub or during app registration. As of February 2026, Backend Systems applications must have a JKU (JSON Web Key Set URL) when enabled.
2. Your server creates a signed JWT assertion containing your client_id, the token endpoint as the aud (audience), and the current timestamp
3. Your server sends the JWT to Epic’s token endpoint using the client_credentials grant type with client_assertion_type of urn:ietf:params:oauth:client-assertion-type:jwt-bearer
4. Epic validates the JWT signature against your registered public key and returns an access token
5. Your server uses the access token to make FHIR API calls

When to use Backend Services:

• Data synchronization and ETL pipelines that run on a schedule
• Population health analytics that process data for many patients
• Bulk data export operations
• System-to-system integrations where no user is present

Scope Management

OAuth scopes control what data your application can access. Epic supports the SMART scopes specification:

• Patient-level scopes: patient/Patient.read, patient/Observation.read, patient/MedicationRequest.read, etc. These restrict access to data for a single patient.
• User-level scopes: user/Patient.read, user/Observation.read, etc. These allow access to data for multiple patients based on the authenticated user’s permissions within Epic.
• System-level scopes: system/Patient.read, system/Observation.read, etc. Used with Backend Services for server-to-server access.
• Launch scopes: launch (EHR Launch), launch/patient (Standalone Launch with patient picker)
• Identity scopes: openid, fhirUser, profile --- used to obtain the authenticated user’s identity

Best practice: Request only the minimum scopes your application needs. Epic organizations can (and do) restrict the scopes available to each application, and requesting overly broad scopes may delay or prevent your app’s approval.

Token Refresh

Access tokens issued by Epic have a limited lifetime (typically 5-60 minutes, depending on the organization’s configuration). For sessions that need to persist beyond the token lifetime:

1. Request the offline_access scope during authorization to receive a refresh token
2. Before the access token expires, send a refresh request to the token endpoint with the refresh token
3. The token endpoint returns a new access token (and possibly a new refresh token)
4. Store refresh tokens securely---they represent persistent access to patient data

Epic App Market and Connection Hub

If your application will be used by multiple Epic organizations, you need to register it through Epic’s App Market (formerly App Orchard) and Connection Hub.

Registration Process

1. Create a developer account at open.epic.com. This gives you access to the sandbox environment, documentation, and the app registration workflow.
2. Register your application. Specify the FHIR resources and scopes your app requires, the launch type (EHR Launch, Standalone, Backend Services), and your app’s redirect URIs.
3. Develop and test in the sandbox. Use Epic’s public sandbox with synthetic patient data to build and validate your integration.
4. Complete the security questionnaire. Epic requires all apps to complete a security and privacy assessment. This covers data handling practices, encryption, access controls, breach notification procedures, and compliance with HIPAA requirements.
5. Request listing in Connection Hub. Once your app is functional and has passed the security review, request a listing. This makes your app discoverable by Epic customers.
6. Epic customer enablement. Individual Epic organizations must explicitly enable your app for their environment. This involves the customer’s IT team reviewing your app’s scope requests and configuring access.

Certification Requirements

Epic’s app certification evaluates several dimensions:

• Functional validation: Your app must work correctly against the Epic environment. Test with real Epic workflows, not just isolated API calls.
• Security compliance: Adherence to Epic’s security standards, which align with HIPAA requirements and industry best practices.
• US Core conformance: If your app reads or writes clinical data, it must handle US Core profiles correctly.
• Error handling: Your app must handle API errors, expired tokens, missing data, and network failures gracefully.
• Performance: Your app must not degrade Epic system performance. This includes respecting rate limits and avoiding excessive API calls.

Review Timeline

Plan for 4-8 weeks from submission to listing approval, though timelines vary. Complex apps with broad scope requests or novel use cases may take longer. Engage with Epic’s vendor services team early if you anticipate a complex review.

When to Skip the App Market

Not every Epic integration requires App Market listing:

• Single-site integrations where your app is used by only one Epic organization can be configured directly through that organization’s IT team using a non-production client ID.
• HL7 v2 interfaces are configured through Epic Bridges and do not go through the App Market.
• Backend Services integrations for data analytics or population health may be configured directly if they serve a single customer.

HL7 v2 Integration

Despite the momentum behind FHIR, HL7 v2 interfaces remain essential for many Epic integration scenarios. Epic Bridges is the module that manages HL7 v2 message routing, and it handles a massive volume of messages across Epic’s installed base.

ADT Messages (Admit/Discharge/Transfer)

ADT messages are the backbone of patient flow integration. Key message types include:

ADT feeds from Epic are typically configured as outbound interfaces through Bridges. The receiving system connects via TCP/IP using the MLLP (Minimum Lower Layer Protocol) and must send HL7 ACK messages to confirm receipt.

Order Messages (ORM/OML)

Order messages flow from Epic to ancillary systems (lab, radiology, pharmacy) to communicate clinical orders:

• ORM^O01: General order message, used for lab orders, radiology orders, and other ancillary orders.
• OML^O21: Lab order message (newer HL7 v2.5.1 format that some labs prefer).

Order messages include the ordering provider, order details (tests requested, priority, specimen requirements), patient demographics, and insurance information. Your receiving system must parse these messages, execute the order, and return results.

Result Messages (ORU)

Result messages flow from ancillary systems back to Epic:

• ORU^R01: Unsolicited observation result. This is the primary message type for delivering lab results, radiology reports, and other diagnostic results back to Epic.

Result messages must include the patient identifier, order number, result values, units, reference ranges, abnormal flags, and result status (preliminary, final, corrected). Epic Bridges validates inbound ORU messages against the original order and routes results to the appropriate provider’s inbox.

Scheduling Messages (SIU)

Scheduling messages support bidirectional appointment synchronization:

• SIU^S12: New appointment notification
• SIU^S13: Appointment rescheduled
• SIU^S14: Appointment modified
• SIU^S15: Appointment cancelled
• SIU^S26: Patient did not show

These messages are critical for integrating external scheduling systems, patient engagement platforms, and resource management tools with Epic’s scheduling module.

Configuring Bridges Interfaces

Epic Bridges interfaces are configured by the Epic customer’s IT team (or with Epic’s assistance). Key configuration elements include:

• Connection type: TCP/IP with MLLP is the standard transport.
• Message format: HL7 v2.x (typically v2.3, v2.4, or v2.5.1, depending on the interface type and the Epic version).
• Filtering and routing: Bridges can filter messages based on message type, patient location, ordering department, and other criteria.
• Translation: Bridges can perform code translations (e.g., mapping Epic internal codes to external code systems like LOINC or CPT).

Integration Engine Routing

For organizations with multiple HL7 v2 interfaces, an integration engine like Mirth Connect is commonly deployed between Epic Bridges and the downstream systems. The integration engine handles:

• Message routing to multiple destinations based on content
• Format translation between different HL7 v2 versions
• Code system mapping
• Error handling and message retry logic
• Audit logging and message archiving

MyChart Integration

MyChart is Epic’s patient portal, and it provides several integration pathways for patient-facing applications.

MyChart API Capabilities

• Appointment scheduling: Search for available appointments and book on behalf of the patient.
• Secure messaging: Send and receive messages between patients and care teams.
• Health records access: Patients can access their clinical data through FHIR APIs using the patient-facing authorization flow.
• Questionnaires: Deliver patient-reported outcome measures and intake forms through MyChart.
• Proxy access: Caregivers and legal guardians can access records for dependents.

Patient-Facing FHIR

For patient-facing apps, Epic supports the SMART on FHIR Standalone Launch flow with patient authentication through MyChart credentials. The patient authenticates directly (no clinician involved), and the app receives an access token scoped to that patient’s data. This is the pathway used for patient health record aggregation apps and personal health platforms.

Integration Considerations

• Patient identity verification. MyChart uses its own authentication, which may include multi-factor authentication. Your app must handle the full authentication flow, including potential MFA prompts.
• Data scope. Patient-facing apps can only access data that the patient would see in MyChart. Some clinical data may be withheld pending provider review (e.g., pathology results with a release delay).
• Proxy relationships. If your app supports caregiver access, you must handle MyChart proxy relationships correctly, including age-based access restrictions for adolescent patients.

CDS Hooks

CDS Hooks is a standards-based specification that enables external services to provide clinical decision support directly within the Epic workflow. When a clinician performs a specific action in Epic (such as opening a patient chart or signing an order), Epic calls your CDS service, and your service returns recommendations that are displayed inline.

How CDS Hooks Work

1. Hook trigger. Epic detects a workflow event that matches a registered hook (e.g., patient-view, order-select, order-sign).
2. Service call. Epic sends an HTTP POST request to your CDS service with context data (patient ID, encounter ID, draft orders, etc.).
3. Card response. Your service processes the context data and returns one or more “cards”---structured responses that Epic displays to the clinician.
4. Clinician action. The clinician can accept suggestions, dismiss cards, or launch a SMART app for more detail.

Hook Types

Card Response Structure

Each card returned by your CDS service includes:

• Summary: A brief, actionable headline (displayed prominently in Epic).
• Detail: Additional context in Markdown format.
• Indicator: Urgency level (info, warning, critical) that controls the card’s visual presentation.
• Suggestions: Actionable items the clinician can accept with a single click (e.g., “Add allergy to chart,” “Order recommended test”).
• Links: URLs that launch a SMART app or external resource for more information.

Implementation Considerations

• Latency matters. Epic expects CDS service responses within 500 milliseconds to 2 seconds. Clinicians will not wait for slow decision support. Design your service for low-latency responses with pre-computed data where possible.
• Card fatigue. Returning too many cards or low-value alerts leads to clinicians ignoring all CDS recommendations. Be selective about when you return cards and prioritize high-impact, actionable recommendations.
• Epic-specific behaviors. While CDS Hooks is a standard specification, Epic’s implementation has some specific behaviors. Epic also supports Best Practice Alerts (BPAs) as a native clinical decision support mechanism. For some use cases, a BPA may be more appropriate than a CDS Hook. Discuss the trade-offs with the Epic customer’s clinical informatics team.

Testing Your Integration

Thorough testing is critical for any Epic integration. Epic provides several tools and environments to support the testing process.

Epic Sandbox Environment

The public sandbox at fhir.epic.com provides:

• A FHIR R4 server with synthetic patient data
• SMART on FHIR authorization flows (EHR Launch and Standalone)
• A web-based EHR simulator for testing EHR Launch flows
• Pre-configured test patients with diverse clinical data

Register for a free developer account at open.epic.com to access the sandbox. The sandbox is the right environment for initial development and basic functional testing.

Test Patients and Scenarios

Epic’s sandbox includes test patients designed to cover common clinical scenarios:

• Patients with active medications, allergies, and problem lists
• Patients with recent lab results and vital signs
• Patients with multiple encounters and complex histories
• Pediatric patients (for testing age-specific logic)
• Patients with minimal data (for testing empty-state handling)

Design your test plan to cover both data-rich and data-sparse scenarios. Your app must handle missing data gracefully rather than crashing or displaying errors.

Inferno Testing

The ONC Inferno testing tool validates US Core conformance for FHIR servers and client applications. While Inferno is primarily aimed at FHIR server certification, it is also valuable for client developers to verify that their apps correctly handle US Core profiles. Run your app against Inferno’s test suites to catch conformance issues before submitting for Epic review.

Common Testing Pitfalls

• Hardcoded URLs. Never hardcode the FHIR server URL or authorization endpoints. Always use the SMART discovery mechanism (.well-known/smart-configuration) to resolve endpoints dynamically.
• Assuming data presence. Not all patients have all data types. Test with patients who lack allergies, medications, or problem list entries to ensure your app handles empty result sets.
• Ignoring pagination. Search results that exceed Epic’s page size are paginated. If your app does not follow pagination links, it will miss data.
• Token expiration. Test what happens when an access token expires mid-session. Your app should detect 401 responses and use the refresh token to obtain a new access token seamlessly.
• Scope restrictions. Individual Epic organizations may grant fewer scopes than you request. Test your app’s behavior when certain scopes are denied.

Becoming an Epic Integration Partner

For vendors seeking a deeper relationship with Epic, the integration partner program provides additional resources and visibility. This section addresses the “epic integration partners” keyword directly---here is what the partnership pathway looks like.

Partnership Tiers

Epic’s partner ecosystem includes several levels of engagement:

• Registered developer. The entry point. Register at open.epic.com, access the sandbox, and build your integration. No formal partnership required.
• App Market listed. Your app has passed certification and is listed in Connection Hub. Epic customers can discover and enable your app.
• Integration partner. A deeper relationship that may include co-development opportunities, early access to new APIs, joint marketing, and dedicated support contacts. Partnership is typically reserved for vendors with a proven track record and significant customer overlap with Epic.

Ongoing Compliance

Once your app is listed in the App Market or you have established integration partnerships, ongoing compliance is required:

• Annual security reviews. Epic requires periodic re-attestation of your security practices.
• API version updates. When Epic releases new FHIR API versions or deprecates older endpoints, you must update your integration within the specified timeline.
• Incident reporting. If your app experiences a security breach or data incident, you must notify Epic and affected customers.
• Performance monitoring. Epic monitors the API usage patterns of listed apps. Apps that generate excessive load or exhibit problematic patterns may have their access restricted.

Common Integration Patterns

Across the hundreds of Epic integrations we have worked on, several common patterns emerge. Understanding these patterns helps you choose the right technical approach for your specific use case.

Clinical Data Synchronization

Use case: Keeping an external clinical system (analytics platform, care management tool, specialty application) synchronized with Epic clinical data.

Recommended approach: Backend Services authorization with FHIR Bulk Data export for initial load, followed by incremental polling using FHIR search with _lastUpdated parameter. For near-real-time needs, supplement with HL7 v2 ADT and ORU feeds through Bridges.

Population Health Feeds

Use case: Extracting data for population health analytics, quality measurement, and risk stratification.

Recommended approach: FHIR Bulk Data Access (the $export operation) for large-scale data extraction. Bulk Data is designed for exactly this use case and is far more efficient than making individual FHIR API calls for thousands of patients.

Patient Engagement Apps

Use case: Patient-facing app for health record access, appointment scheduling, medication adherence, or remote monitoring.

Recommended approach: SMART on FHIR Standalone Launch with patient authentication through MyChart. Use patient-level FHIR scopes to access the authenticated patient’s data.

Revenue Cycle Integration

Use case: Prior authorization automation, claims status checking, eligibility verification.

Recommended approach: A combination of FHIR Coverage and ExplanationOfBenefit resources for insurance data, and HL7 v2 or X12 EDI transactions for claims workflows. The Da Vinci Implementation Guides (Prior Authorization Support, Coverage Requirements Discovery) provide FHIR-based approaches that are gaining adoption.

IoT and Device Data

Use case: Ingesting data from medical devices (vital signs monitors, infusion pumps, wearables) into Epic.

Recommended approach: For bedside devices, HL7 v2 ORU messages through Bridges remain the standard. For remote patient monitoring devices, FHIR Observation resources via Backend Services APIs or through a device integration platform that handles the device-to-FHIR translation.

Clinical Decision Support

Use case: Providing real-time alerts, recommendations, or risk scores within the Epic workflow.

Recommended approach: CDS Hooks for lightweight, synchronous decision support that displays inline in Epic. For more complex workflows that require user interaction, combine CDS Hooks with a linked SMART on FHIR app that the clinician can launch from the CDS card.

Next Steps

Integrating with Epic is a significant technical undertaking, but the pathways are well-defined and the tooling is mature. Here is how to get started:

1. Define your use case clearly. The right integration approach depends entirely on what you are trying to accomplish. A patient-facing app, a clinical decision support tool, and a data analytics pipeline each require different pathways.
2. Register at open.epic.com. Create your developer account, set up your app registration, and start building against the sandbox. This costs nothing and gives you hands-on experience with Epic’s FHIR APIs.
3. Choose your authorization pattern. EHR Launch for clinician-facing apps embedded in Epic, Standalone Launch for independent apps, Backend Services for server-to-server integrations.
4. Build and test iteratively. Start with basic API calls in the sandbox, then add complexity. Test with diverse patient scenarios, including edge cases.
5. Plan for the App Market. If you are building a product for multiple Epic customers, begin the App Market listing process early. The security review and certification process takes time.

Saga IT has extensive experience building Epic integrations across all of these pathways. Whether you need help with FHIR API development, HL7 v2 interface configuration, SMART on FHIR app authorization, or end-to-end integration architecture, our team can accelerate your project.

• Epic Integration Services --- Our full Epic integration practice, from architecture through production support.
• FHIR API Integration --- FHIR R4 development, US Core conformance, and Bulk Data implementation.
• EHR Integration --- Cross-platform EHR integration for multi-vendor environments.
• HL7 Integration Services --- HL7 v2 interface development, testing, and optimization.
• HL7 Workbench --- Our free online HL7 message parser and validator for testing your HL7 v2 integrations.