How to Integrate a Third-Party App with Epic EHR | Guide 101

Posted in EPIC

Epic powers many of the largest health systems worldwide, and seamless Epic EHR API integration is now essential for health app adoption, interoperability, and measurable care outcomes. Over 300 million patients have a current electronic record in Epic, underscoring the platform’s global scale and the potential reach of your integration (see Epic by the numbers). At a high level, integrating a third-party app with Epic EHR means enrolling in Epic’s Showroom program, aligning use cases to SMART on FHIR and HL7 endpoints, authenticating with OAuth 2.0, validating workflows in Epic sandboxes, and then deploying site-by-site under Epic’s federated model.

Done effectively, teams unlock Epic EHR integration benefits like real-time clinical context, write-back where supported, and embedded workflows that minimize clicks and cognitive load. Capabilities span patient records, scheduling, medications, labs, imaging, and more, enabled through standardized APIs and launch patterns documented in the Epic interoperability overview (SMART on FHIR, FHIR, Care Everywhere) that emphasize secure, compliant exchange and in-workflow usability (see Epic interoperability overview).

Definition

EHR API integration is the secure, standards-based exchange of clinical data and actions between an application and an electronic health record to enable in-workflow features, decision-making, and automations—while complying with HIPAA/GDPR, consent, and audit requirements.

Understanding Epic’s API Ecosystem and Standards

Overview of Epic Showroom and Federated Model

Epic’s official partner program, the Epic Showroom (formerly App Orchard), is the entry point for third-party integration. Through the Epic Developer Resources, teams enroll, discover APIs, obtain sandbox credentials, and complete security reviews prior to production listing (see Epic Developer Resources). The Showroom currently organizes offerings into tiers like Connection Hub, Toolbox, and Workshop—each providing different documentation, testing tools, and listing options.

Epic uses a federated model: every health system runs its own Epic instance and governance. There is no single “global” production endpoint; instead, you establish relationships, credentials, and approvals with each customer site. Expect administrative work per deployment, from security risk assessments to VPN or network approvals. Many developers report a modest annual Connection Hub fee (e.g., circa $500), plus additional costs for higher-tier tools and listing; always confirm current pricing with Epic. A practical onboarding path is: enroll in Showroom, identify target APIs, pass security checks, test in sandboxes, secure site sponsorship, and then deploy to each site’s production per policy (see Epic federated model overview).

• Epic Showroom enrollment: discover APIs, request sandboxes, submit app materials
• Site-by-site enablement: IT/security review, environment mapping, contract updates
• Ongoing maintenance: version updates, monitoring, and support SLAs

Role of HL7 FHIR and USCDI in Epic Integration

HL7 defines healthcare messaging standards; FHIR is HL7’s modern, RESTful API specification for representing and exchanging clinical data; USCDI is a core set of standardized clinical data classes that U.S. EHRs must make available for interoperability. Together, HL7 & FHIR integration standardize payloads, semantics, and access so your app can read and write safely across Epic sites with consistent expectations for scopes, fields, and security.

Common FHIR resources used in Epic integrations:

• Patient, Practitioner, Organization
• Encounter, Appointment, Schedule, Slot
• Observation, Condition, Procedure, DiagnosticReport, ImagingStudy
• MedicationRequest, Medication, MedicationStatement
• AllergyIntolerance, Immunization
• CarePlan, CareTeam, Task
• DocumentReference, Binary (notes, attachments)

Map each feature to FHIR resources and USCDI elements early. For example, a vitals dashboard touches Observation; medication reconciliation spans MedicationRequest and MedicationStatement; scheduling uses Appointment/Schedule/Slot. Clear mapping reduces rework, speeds security reviews, and ensures compliance with the 21st Century Cures Act.

SMART on FHIR and OAuth 2.0 Authentication Framework

SMART on FHIR is a standards-based way for third-party apps to connect to EHRs using FHIR resources with consistent authorization, context passing, and launch flows—so apps can run inside or alongside the EHR with appropriate scopes and user/patient context (see SMART on FHIR walkthrough). OAuth 2.0 underpins authentication/authorization, enabling HIPAA-compliant flows with least-privileged access and auditable consent. In Epic, scopes and launch parameters convey patient and user context to your app.

Common auth scenarios:

• EHR launch: Clinician launches the app from Hyperspace/Canto/Haiku with user/patient context.
• Standalone launch: App starts outside Epic, then requests Epic authorization and context.
• Backend service: System-to-system job uses OAuth 2.0 client credentials for non-user flows.
• Mobile with PKCE: Public clients (native/mobile) use PKCE for secure token exchange.

Planning Your Epic Integration Project

Defining Use Cases and Required API Endpoints

Start with workflows, not endpoints. Document the user journeys you must support—read-only views (e.g., labs, medications), write-back (e.g., notes, orders where allowed), and enrollment/onboarding. Map each to FHIR operations (read, search, create, update) or HL7v2 messages when needed. 

Create a requirements matrix tying features to Epic endpoints, scopes, and regulations (HIPAA, 21st Century Cures). Some workflows (such as patient enrollment, ADT events, or specific billing feeds) may require hybrid approaches that combine FHIR and HL7v2 or use Epic interfaces beyond pure FHIR due to write limitations or event-trigger needs (see startup integration realities).

Navigating Compliance: HIPAA, GDPR, and Information Blocking

• HIPAA: Treat all PHI with strict access controls, encryption in transit/at rest, and audit logging. Execute BAAs with provider customers, clarify breach response, and define minimum necessary principles.
• GDPR: If serving EU residents, implement lawful bases, explicit consent where required, data minimization, DSR workflows, and cross-border controls.
• Information Blocking: Ensure patients and authorized clinicians can access USCDI data without undue delay; document any necessary exceptions.

Bake privacy-by-design into architecture; schedule periodic compliance reviews; and maintain immutable audit logs across auth, access, and data changes.

Engaging Epic Showroom and Organizational Onboarding

Operational readiness is as important as code:

• Register in Epic Showroom, request sandboxes, review security requirements, and prepare documentation packages (threat model, data flows, DPIA/TRA).
• Identify pilot customer(s) early. In Epic’s federated world, each site’s IT/security, networking, and clinical governance must sign off.
• Onboarding checklist:
  • Showroom enrollment and sandbox credentials
  • App submission and security review
  • Site sponsorship, contracts/BAA updates
  • Environment/network prerequisites (VPN, allowlists)
  • Test plan and cutover schedule

For deeper guidance, Epic’s developer resources outline sandboxes, launch parameters, scopes, and listing processes (see Epic Developer Resources).

Step-by-Step Epic Integration Process (End-to-End)

• Define clinical workflows and outcomes: Validate the problem, target users (patient vs clinician), and success metrics. Prioritize read-only vs write-back scenarios to right-size scope.
• Map to standards and endpoints: Align each feature to FHIR resources/operations and USCDI elements; note any HL7v2 or hybrid needs where FHIR write-back is limited (see FHIR and USCDI basics and startup integration realities).
• Enroll in Epic Showroom: Create an account, review tiers, request sandboxes, and confirm current fees and listing requirements (see Epic Developer Resources).
• Design your security and compliance posture: Complete threat modeling, data-flow diagrams, HIPAA safeguards, GDPR controls (if applicable), BAAs, and minimum-necessary access principles.
• Plan SMART on FHIR launch flows: Choose EHR launch, standalone, backend service, and/or mobile (PKCE). Define OAuth 2.0 scopes, redirect URIs, and context parameters (see SMART on FHIR walkthrough).
• Stand up infrastructure and developer tooling: Containerize services (Docker), set up CI/CD, secrets management, and IaC. Prepare API debugging and validation tools.
• Implement core API clients and data models: Build FHIR client wrappers, handle patient/encounter context, paging, and idempotency. Define error handling and retries with backoff.
• Build the MVP integration: Implement prioritized read paths (e.g., Patient, Encounter, Observation) and any feasible writes (e.g., DocumentReference) with least-privilege scopes.
• Test in Epic sandboxes: Run unit/integration tests, negative/permission tests, and data-shape verification across key resources. Validate SMART launches and token handling.
• Performance and resilience tests: Execute load tests, inject faults (token expiry, network/VPN issues), and verify observability (metrics, logs, audits) before engaging a site.
• Secure pilot site sponsorship: Align on clinical champions and IT/security contacts. Exchange documentation packages and begin site-specific reviews and approvals.
• Complete site connectivity and registration: Configure VPN/allowlists/mTLS as required; register OAuth clients per site; align SSO/RBAC and environment URLs.
• Validate in non-production at the site: Map environments (DEV/TEST/TRN), run end-to-end scenarios with test patients, complete UAT, and capture clinical sign-off.
• Plan release and rollback: Choose blue–green/canary, finalize runbooks, enable kill switches, and pin versions/database snapshots for safe cutover.
• Go live with the pilot: Monitor latency, error rates, and scope usage; triage issues with site IT; keep detailed audit trails for compliance.
• Stabilize and reconcile: Verify write-backs via read-back and reconciliation jobs; address edge cases; update runbooks and configuration based on learnings.
• Scale to additional sites: Templatize per-site configs, automate environment verification, formalize SLAs, and manage versioning across tenants in the federated model.
• Expand capabilities and analytics: Add advanced workflows (e.g., decision support), and, where appropriate, integrate Clarity-to-Delta Lake pipelines for analytics without burdening transactional APIs.

Technical Architecture and Environment Setup

Choosing Technology Stack and Infrastructure

Select proven, testable stacks that your team can secure and scale:

• Languages/testing: Python with pytest, Java with JUnit, Node.js with Mocha for unit/integration testing and FHIR payload validation (see recommended toolchains for Epic).
• Packaging/orchestration: Docker for immutable artifacts; Kubernetes for scaling and high availability.
• Developer tooling: Visual Studio Code, PyCharm, and API debuggers (Postman/Insomnia) for rapid iteration.

Adopt 12-factor practices, secrets management (e.g., HashiCorp Vault/KMS), and IaC (Terraform) to standardize deployments and support audits.

Handling Site-Specific Connectivity and Security Requirements

Many Epic sites require secure channels (VPN, Direct Connect, or TLS mutual auth) for API and interface traffic, which can constrain pure cloud-native models. Clarify early:

• Network: IP allowlists, TLS ciphers, mutual TLS, proxy rules
• Identity: OAuth client registration per site, SSO strategies, RBAC
• Messaging: Interface engines such as Mirth Connect or Epic Bridges can route HL7v2 ADT/ORM/ORU messages, transform schemas, and buffer during downtime (see Epic integration options overview).

Document these per site to avoid late-stage surprises.

Containerization and Deployment Best Practices

• Pipeline: Build → scan (SAST/DAST/containers) → sign images → deploy to Kubernetes with declarative manifests and policy gates.
• Release strategy: Blue–green or canary deployments enable safe rollouts and rapid rollback when clinical risk emerges (see Epic integration benefits and challenges).
• CI/CD: Use GitHub Actions or GitLab CI for versioning, approvals, and traceability; retain artifacts and logs to support compliance audits.

Development and Testing Best Practices

Implementing and Validating FHIR and HL7 Endpoints

Use FHIR/HL7 validators and robust unit/integration tests to ensure schema conformance and predictable behavior across sites. Pay special attention to:

• Patient matching and context: Confirm IDs, MRNs, and encounter context on every call; some operations are per-patient and do not allow bulk access.
• Search parameters and paging: Honor server constraints; cache judiciously.
• Hybrid workflows: For enrollment and event-driven use cases, combine FHIR reads with HL7v2 ADT/event feeds to ensure timeliness and coverage (see startup integration realities).

Using Epic Sandboxes and Developer Tools

Epic Showroom provides sandbox environments that mirror production behaviors for SMART on FHIR launches, scopes, and data models. Utilize:

• Interactive testing with Postman/Insomnia; automate with pytest/JUnit and end-to-end suites (e.g., Cypress).
• Negative testing for permissions, scopes, and context failures.
• Data shape verification across Patient, Observation, MedicationRequest, and more, as outlined in practical integration guides (see health app Epic integration walkthrough).

Performance Testing and Fault Injection Strategies

Before go-live, run load tests in Epic sandboxes to validate throughput, latency, and rate limits. Add fault injection to simulate:

• Token expiry and auth server outages
• Network partitions/VPN failure
• Slow downstreams and timeouts

Instrument with Prometheus/Grafana or AWS CloudWatch to track p95 latency, error budgets, and saturation metrics. These practices support certification/readiness and reduce post-launch incidents (see Epic integration benefits and challenges).

Integration Patterns and Workflow Alignment

Understanding SMART Launch, Ribbon, and Decision Workflow Models

Choose launch and decision support models that fit clinical reality:

Model	Best for	Pros	Cons	Technical notes
EHR launch (SMART)	Clinician workflows	In-context patient/user, minimal clicks	Requires EHR enablement per site	SMART context, OAuth; Hyperspace/Canto/Haiku
Standalone launch (SMART)	Patient apps, external portals	Works outside EHR; broad reach	Extra steps to obtain context	OAuth with user auth; link accounts to Epic
SMART Ribbon	Quick glance in-chart	Zero/low-click insights	Limited surface area	Lightweight UI; context-driven
In-workflow/Decision support	Clinical decision-making	High adoption, embedded	More governance/validation	CDS Hooks/alerts where available; policy review

Align with existing clinical pathways to boost adoption and reduce disruption; mapping features to FHIR/USCDI upfront streamlines governance (see FHIR and USCDI basics).

Patient-Facing vs Clinician-Facing Integration Considerations

Patient-facing (e.g., via MyChart or standalone):

• Typical journeys: account linking, consent management, viewing labs/medications, appointment scheduling, remote monitoring uploads
• Considerations: plain-language content, granular consent, notifications, and secure mobile authentication (PKCE)

Clinician-facing (Hyperspace/Canto/Haiku):

• Typical journeys: in-chart launch, context-aware summaries, documentation aids, order suggestions, tasking
• Considerations: minimal click burden, fast load times, audit trails, role-based access, downtime strategies

Both require clear consent/audit flows, least-privilege scopes, and transparent data use.

Managing Write-Back Limitations and Hybrid Approaches

FHIR write-back in Epic can be constrained, especially for orders, billing, or enrollment. Where direct FHIR writes are unsupported or gated, use hybrid patterns:

• HL7v2 via interface engines for ADT/ORM/ORU and event-driven updates
• Tasking or inbox workflows to request clinician action
• DocumentReference for attachments when structured writes aren’t feasible

Document every write path, add reconciliation checks, and monitor for discrepancies to maintain safety and regulatory compliance.

Deployment, Monitoring, and Scaling

Pilot Launch, Staged Rollout, and Rollback Planning

Pilot with a small cohort/site, then utilize blue–green or canary releases to expand. Prepare:

• Rollback plans with version pinning and database snapshots
• Clinical safety checks and “kill switches”
• Site-specific runbooks and readiness checklists (security, networking, training)

Runtime Monitoring and Analytics Pipelines

Track:

• Availability: uptime, error rates, retry storms
• Performance: p50/p95 latency, throughput, queue depth
• Security/compliance: auth failures, scope anomalies, audit trails

Use Prometheus/Grafana or CloudWatch for metrics and alerts; centralize logs and audits; implement continuous compliance dashboards for HIPAA/GDPR and information blocking.

Scaling with Clarity Databases and Delta Lake Architectures

Epic Clarity is Epic’s reporting database optimized for large analytical queries. To avoid burdening production APIs, replicate or stream data to analytic stores (e.g., Databricks with Delta Lake) for near-real-time pipelines, advanced cohorting, and ML workflows—while enforcing PHI governance and access controls. This pattern supports use cases like early sepsis alerts, length of stay prediction, and population health dashboards without impacting transactional performance (see Clarity-to-Delta Lake approach).

Common Challenges and Risk Mitigation

Typical Integration Failure Points and How to Avoid Them

Common failure modes and fixes:

• Poor workflow fit → run shadowing sessions, usability tests, and map to SMART launch points
• Insufficient testing → add sandbox end-to-end, load, and fault injection
• Security/configuration drift → codify infrastructure with IaC, use policy-as-code and secrets management
• Incomplete regulatory coverage → maintain a living compliance matrix and periodic reviews

Pre-launch checklist:

• Security attestations complete
• End-to-end and load tests passing
• Runbooks and rollback plans validated
• Site approvals and cutover schedule signed off

Coordination with Healthcare IT Teams and Epic Support

Establish an engagement and escalation plan:

• Weekly standups during build/test, daily during cutover
• Shared documentation: architecture, data flows, test scripts, change logs
• Clear SLAs and on-call rotations, with audit-ready change management

Balancing Development Effort with Operational Negotiations

Plan budgets with operations in mind; technical build is often only half the work. A typical breakdown:

Workstream	Estimated share
Engineering (APIs, auth, testing)	40–60%
Security, compliance, legal (BAA, DPIA)	15–25%
Site onboarding (IT, networking, governance)	20–30%
Training, change management, documentation	5–10%

Expect ongoing costs for multi-site negotiations, compliance updates, and monitoring.

Market Strategy and Alternative Access Options

Cost and Timeline Considerations for Epic Integration

Budget elements include Showroom fees, engineering, security reviews, sandbox and certification work, and multi-site deployments. MVP integrations can be delivered in 3–6 months for focused read-only use cases; write-back, decision support, and multi-site scale commonly extend timelines. Consider trade-offs between direct Epic APIs and accelerators (integration platforms, partner networks) to speed market entry.

Leveraging National Exchange Networks and Multi-EHR Strategies

National networks like TEFCA frameworks and Carequality-style exchanges can supplement Epic APIs for cross-organization data aggregation, payer analytics, and patient-mediated access. They fit best when your product spans many providers/payers or when basic read access suffices. Maintain optionality: support both direct Epic integration where workflow depth is required, and national networks for breadth.

Partnering with Epic Vendor Member Folio3 Digital Health 

Folio3 Digital Health is an Epic Vendor member that offers Epic-related services. We can normalize connectivity across Epic and other EHRs, reduce interface variance, and accelerate security reviews. For expert help across this spectrum, see Digital Health Folio3’s Epic integration services.

Conclusion

Epic EHR API integration succeeds when technology and operations move in lockstep: define workflow-first use cases, align to SMART on FHIR/USCDI, design for security and compliance from day one, validate thoroughly in sandboxes, and plan for site-by-site onboarding within Epic’s federated model. Pair resilient cloud-native architecture with clear governance, monitoring, and rollback strategies. Whether you build direct or leverage integration partners, a staged rollout, strong clinical alignment, and continuous measurement will turn interoperability into tangible outcomes for patients and clinicians.

Frequently Asked Questions

What authentication method should be used for Epic integration?

SMART on FHIR with OAuth 2.0 to support EHR launch, standalone launch, backend services, and mobile (PKCE) with least-privilege scopes.

How do federated connections affect app deployment?

Epic’s federated model means you must onboard and configure your app with each health system’s Epic environment individually.

Which FHIR APIs are essential for common clinical workflows?

Start with Patient, Encounter, Observation, MedicationRequest, Appointment, and DocumentReference; add others as your workflows expand.

How can one ensure HIPAA compliance when integrating with Epic?

Execute BAAs with provider customers, enforce encryption and RBAC, and maintain comprehensive audit logging and breach response plans.

What tools and platforms support efficient Epic API development?

Use Postman/Insomnia for API calls, pytest/JUnit for automation, Prometheus/Grafana for monitoring, and Epic sandboxes for end-to-end validation.

How long does Epic Showroom enrollment and security review take?

Timelines vary by app scope and responsiveness, but expect several weeks for enrollment, sandbox access, submission, and security review. Build buffer time into your project plan and pilot with a sponsor site to accelerate approvals.

What’s the difference between Epic sandboxes and production environments?

Sandboxes mirror production launch flows and data models but use synthetic data and standardized configurations. Production is site-specific; validate environment URLs, auth clients, scopes, and network paths for each deployment.

How should API rate limits and throttling be handled?

Individual Epic sites may enforce rate limits. Implement client-side caching, request batching where appropriate, idempotency, and exponential backoff with jitter. Monitor 429/5xx responses and coordinate with site admins on agreed throughput.

How can configuration across multiple Epic sites be managed?

Externalize site-specific settings (endpoints, OAuth clients, scopes, network rules) via configuration management and feature flags. Maintain per-site runbooks, automate environment verification, and version your integration contracts.

What strategies ensure safe write-back and reconciliation?

Use least-privilege scopes, confirm context (patient/encounter), and prefer structured writes where supported. When using hybrid approaches (HL7v2, DocumentReference, tasking), add read-back verification, reconciliation jobs, and comprehensive audit trails.

About the Author