.png)
Epic Integration Guide
Epic integrates with enterprise systems primarily through FHIR REST APIs, SMART on FHIR authentication, bulk data access, selected event notifications, and customer-specific HL7v2 interfaces.
Epic integration options at a glance
Epic’s principal modern integration mechanism is FHIR over REST, with resource reads, searches, and customer-approved write operations varying by environment. SMART on FHIR and OAuth 2.0 support user, patient, and backend-services access, while bulk asynchronous exports support large-scale data processing. Selected environments may provide FHIR Subscription or related event notifications, but coverage is not universal. Epic customers also commonly use HL7v2 interfaces for ADT, orders, results, and scheduling. DocumentReference and Binary can support approved document retrieval, while Clarity or Caboodle access is customer-specific. Martini can orchestrate these interfaces, transform FHIR JSON or HL7 payloads, expose normalized APIs, and manage retries and reconciliation.
| Integration point | Supported by Epic? | Common use cases | How Martini supports it |
|---|---|---|---|
| FHIR REST APIs | Yes | Read and search Patient, Encounter, Appointment, Observation, MedicationRequest, and other FHIR resources; customer environments may also enable selected writes. | Martini can consume HTTPS REST endpoints, follow FHIR bundle links, map JSON resources, and orchestrate approved reads or writes. |
| Bulk and asynchronous APIs | Yes | Population-level or large-volume exports using asynchronous job initiation, polling, and NDJSON output. | Martini can initiate jobs, poll status, download results, process resource files in batches, and persist checkpoints for reconciliation. |
| OAuth 2.0 and SMART on FHIR | Yes | User, patient-context, and backend-services authorization with scopes such as patient, user, or system resource access. | Martini can manage external API authentication configuration and use environment-held credentials, scopes, tokens, and approved private-key or JWT settings. |
| FHIR subscriptions and event notifications | Limited | Near-real-time notifications for selected resources and events where the Epic environment enables the required subscription or callback mechanism. | Martini can expose an API or webhook workflow, validate incoming notifications, retrieve the current resource, and reconcile missed or duplicate events. |
| HL7v2 interfaces | Yes | ADT, ORM, ORU, SIU, document, order, result, and interface-engine workflows configured by the Epic customer. | Martini can process supported HL7 or XML payloads delivered through enterprise endpoints, apply routing and transformation, and handle acknowledgements through the surrounding interface design. |
| Document and binary content | Limited | Discover and retrieve approved clinical documents through DocumentReference and Binary, subject to authorization and local configuration. | Martini can retrieve permitted content, preserve metadata and identifiers, validate content type and size, and deliver it to an approved target. |
| SOAP and proprietary web services | Limited | Legacy or implementation-specific web-service integrations where a customer interface contract documents the service. | Martini can consume SOAP services when the specific Epic implementation provides the required contract and authentication details. |
| Database and analytics access | Limited | Customer-managed or licensed Clarity and Caboodle environments for governed reporting and analytics use cases. | Martini can connect to an approved database or analytics endpoint when connectivity, licensing, schema governance, and credentials are provided. |
How Epic exposes data and business events
Epic FHIR REST APIs
Epic’s principal modern interoperability mechanism is FHIR over HTTPS REST. Supported FHIR versions, resources, search parameters, and create or update operations vary by customer environment and application approval.
Martini implementation pattern
Martini implementation pattern: Martini authenticates to the configured Epic FHIR endpoint, retrieves resources or searches, follows server-provided pagination links, transforms FHIR JSON, and sends approved results to downstream systems.
Implementation sequence
Epic bulk and asynchronous APIs
Epic documents bulk data access for large-scale, asynchronous export scenarios. Jobs can produce resource-specific NDJSON files and are intended for population-level processing rather than real-time individual lookups.
Martini implementation pattern
Martini implementation pattern: Martini starts an approved export, polls the job state with bounded backoff, downloads output files, processes them in checkpoints, and reconciles the resulting data with the target system.
Implementation sequence
Epic event notifications
Epic supports FHIR Subscription and related notification mechanisms for selected resources and events. Coverage is partial and depends on the Epic environment, enabled capabilities, channel requirements, and customer approval.
Martini implementation pattern
Martini implementation pattern: Martini exposes a controlled receiving API or workflow, validates the notification, retrieves the current Epic resource when necessary, and uses scheduled reconciliation to detect missed or duplicate events.
Implementation sequence
Epic HL7v2 interfaces
Epic customers commonly use HL7v2 for ADT, orders, results, scheduling, documents, and interface-engine workflows. Message profiles, transport, acknowledgements, and segments are customer-specific.
Martini implementation pattern
Martini implementation pattern: Martini receives an approved HL7 or XML payload through an enterprise endpoint, parses and validates the message, maps it to a canonical event, routes it by message type, and records acknowledgement or error status.
Implementation sequence
Epic documents and binary content
DocumentReference and Binary can support discovery and retrieval of approved clinical documents. Underlying content may require additional authorization and can be constrained by document type, patient context, or customer configuration.
Martini implementation pattern
Martini implementation pattern: Martini searches or receives a DocumentReference, retrieves permitted binary content, validates content metadata, and delivers the document to an approved archival or case-management destination.
Implementation sequence
Common Epic integration patterns
Pattern 1: Synchronize patients and appointments
When to use this pattern
Use this pattern when a scheduling, engagement, or CRM application needs approved Epic identity and appointment information. It is appropriate for scheduled synchronization when event coverage is unavailable or incomplete.
Integration direction
Example Mapping
| Epic Field | Canonical Field | Target Field |
|---|---|---|
| Patient.identifier | patientId | External Patient ID |
| Patient.name | patientName | Contact Name |
| Appointment.start | appointmentStart | Appointment Start |
| Appointment.status | appointmentStatus | Appointment Status |
Martini implementation pattern
A scheduled Martini workflow runs supported incremental searches, follows pagination links, resolves patient identifiers, normalizes time zones, and upserts downstream objects. It handles cancellations and reschedules as state changes, applies minimum-necessary rules, and retries only transient failures.
Martini capabilities used
- scheduled workflows
- API consumption
- data mapping
- business rules
- idempotency
- error handling
Pattern 2: Distribute clinical results
When to use this pattern
Use this pattern when approved Observation or DiagnosticReport data must reach analytics, care-management, or notification systems. Event notifications can be used where enabled, with scheduled searches and reconciliation as fallback.
Integration direction
Example Mapping
| Epic Field | Canonical Field | Target Field |
|---|---|---|
| Observation.code | resultCode | Measure Code |
| Observation.value | resultValue | Result Value |
| Observation.status | resultStatus | Result Status |
| Observation.subject.reference | patientId | Patient ID |
Martini implementation pattern
Martini receives a selected notification or retrieves results on a schedule, loads related patient and encounter context, preserves coding metadata, applies privacy and routing rules, and publishes a normalized result. Duplicate resource IDs and transient HTTP failures are handled through idempotency and bounded retries.
Martini capabilities used
- event-driven workflows
- API consumption
- JSON transformation
- data mapping
- privacy rules
- retry handling
Pattern 3: Process bulk Epic exports
When to use this pattern
Use this pattern for population-scale extraction where individual FHIR calls would be inefficient. It supports analytics, migration, and governed downstream reconciliation.
Integration direction
Example Mapping
| Epic Field | Canonical Field | Target Field |
|---|---|---|
| Patient.id | sourcePatientId | Patient Key |
| Encounter.period | encounterPeriod | Encounter Date Range |
| Observation.code.coding | clinicalCode | Metric Code |
| Observation.value | metricValue | Metric Value |
Martini implementation pattern
Martini initiates the approved asynchronous export, stores the job state, polls with bounded backoff, processes NDJSON by resource type, and writes checkpointed batches to the target data path. Reconciliation identifies missing, duplicate, or changed resources after completion.
Martini capabilities used
- workflow orchestration
- asynchronous API consumption
- batch processing
- JSON handling
- checkpointing
- reconciliation
Pattern 4: Retrieve and archive clinical documents
When to use this pattern
Use this pattern when an approved downstream document-management or case-management application needs clinical documents referenced by Epic.
Integration direction
Example Mapping
| Epic Field | Canonical Field | Target Field |
|---|---|---|
| DocumentReference.subject | patientId | Recipient Patient ID |
| DocumentReference.type | documentType | Document Type |
| DocumentReference.date | documentDate | Document Date |
| Binary.contentType | contentType | File Content Type |
Martini implementation pattern
A Martini workflow identifies permitted DocumentReference resources, retrieves associated Binary content where authorized, validates size and content type, preserves patient and encounter metadata, and delivers the document. Failed downloads are retried only when transient and duplicate content is detected through stable identifiers or checksums where available.
Martini capabilities used
- API consumption
- file and binary handling
- data mapping
- validation
- business rules
- error handling
Applications commonly integrated with Epic
Epic integrations frequently connect clinical and administrative data with patient engagement, service management, workforce, analytics, communications, and document workflows. Exact interfaces depend on organizational governance, Epic configuration, and approved data-sharing purposes.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize approved patient-service, referral, provider, or engagement information with healthcare CRM workflows. | Epic → Martini → Salesforce | Martini retrieves approved Patient, Practitioner, Appointment, or referral-related data through FHIR, applies identity and privacy rules, and upserts Salesforce objects with correlation and retry handling. |
| ServiceNow | Connect approved operational requests, incidents, facilities workflows, or employee-support processes with Epic-related events. | Epic → Martini → ServiceNow | Martini consumes FHIR or customer-provided HL7v2 messages, normalizes the event, routes it by department or workflow type, and creates or updates ServiceNow records with idempotency controls. |
| Microsoft Teams | Deliver approved appointment, care-coordination, operational, or notification information to collaboration workflows. | Epic → Martini → Microsoft Teams | A Martini workflow receives selected Epic changes or performs scheduled searches, removes unnecessary clinical detail, and sends policy-approved notifications through the Teams-facing API or intermediary endpoint. |
| Workday | Align practitioner, workforce, department, and organizational information with healthcare administration processes. | Workday → Martini → Epic | Martini compares approved Workday and Epic identifiers, maps organizational and practitioner attributes, applies ownership rules, and submits only environment-approved updates or reconciliation results. |
| Tableau | Provide governed clinical, operational, or financial reporting using Epic or Epic analytics data. | Epic → Martini → Tableau | Martini retrieves approved FHIR or analytics-layer data, normalizes resource relationships and coding metadata, and publishes controlled datasets or API responses for Tableau consumption. |
| Power BI | Support operational and population-health reporting from governed Epic data or analytics environments. | Epic → Martini → Power BI | Martini orchestrates scheduled extraction, checkpointing, terminology-preserving transformations, and delivery to an approved Power BI data ingestion path. |
| Twilio | Send approved patient reminders or workflow notifications based on Epic scheduling or status data. | Epic → Martini → Twilio | Martini retrieves Appointment or related status data, checks consent and communication rules, sends eligible messages, and records delivery correlation data without exposing unnecessary PHI. |
| DocuSign | Coordinate approved consent, authorization, or administrative document workflows related to patient or provider processes. | Epic → Martini → DocuSign | Martini uses DocumentReference or approved workflow data to initiate a document process, tracks status callbacks, and reconciles completion against Epic identifiers. |
How to build a Epic integration in Martini
Objective
Establish the Epic environment details, application registration, authorization server configuration, scopes, and approved network path before building the workflow.
Instructions in Martini
- Configure the Epic FHIR base URL and environment-specific endpoints
- Use OAuth 2.0 or SMART on FHIR settings supplied by the Epic customer
- Store client credentials, private keys, and tokens in environment configuration or secrets
- Separate test, acceptance, and production settings
Objective
Select an event, schedule, HL7v2 message, or API request based on the resource coverage and latency requirements of the Epic environment.
Instructions in Martini
- Use a notification mechanism only for resources and events enabled by Epic
- Use scheduled incremental searches when event coverage is incomplete
- Use a Martini API for approved inbound notifications or façade requests
- Use bulk exports for large-scale extraction
Objective
Retrieve the required FHIR resources or receive the approved message, preserving source identifiers and correlation information.
Instructions in Martini
- Follow FHIR bundle next links rather than constructing pagination URLs
- Retrieve related Patient or Encounter context where needed
- Persist continuation state for long-running or bulk workflows
- Validate HL7v2 message structure and transport correlation
Objective
Coordinate calls, transformations, routing, validation, and target delivery as a maintainable Martini workflow.
Instructions in Martini
- Separate acquisition, normalization, business rules, and delivery stages
- Use bounded concurrency and avoid unbounded parallel Epic requests
- Branch by resource, message type, status, or destination policy
- Record workflow correlation and processing status
Objective
Convert FHIR JSON, NDJSON, HL7v2, or document metadata into canonical and target-specific structures without losing healthcare identifiers or coding context.
Instructions in Martini
- Preserve source IDs and approved business identifiers
- Handle optional FHIR elements, extensions, arrays, and references defensively
- Normalize time zones and coding systems according to the target contract
- Apply minimum-necessary data mapping
Objective
Enforce authorization, consent, patient identity, ownership, routing, and write-eligibility rules before data leaves the integration boundary.
Instructions in Martini
- Do not assume read access permits writes to Epic
- Use approved patient and organization cross-references
- Filter sensitive fields according to the receiving system and purpose
- Validate required fields before creating or updating target data
Common Epic data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Patient | Demographics, identifiers, contact information, and administrative identity matching. | Salesforce, patient engagement platforms, analytics stores, and scheduling applications. | Martini maps identifiers and approved demographics, applies minimum-necessary rules, and performs idempotent upserts with cross-reference handling. |
| Practitioner | Clinician and healthcare professional identity, role, and organizational relationships. | Workday, workforce systems, service management platforms, and analytics environments. | Martini preserves source identifiers, maps organization and role attributes, and routes only approved fields to downstream systems. |
| Encounter | Inpatient, outpatient, emergency, telehealth, and other patient visits. | Care-management platforms, analytics systems, billing-related workflows, and operational applications. | Martini links encounters to Patient and Organization identifiers, normalizes status and dates, and applies routing and privacy rules. |
| Appointment | Scheduled visits, availability, cancellations, reschedules, and appointment status. | Scheduling applications, Twilio, Microsoft Teams, Salesforce, and reporting platforms. | Martini follows supported pagination and incremental search behavior, normalizes time zones, and handles reschedules and cancellations idempotently. |
| Observation | Vital signs, laboratory results, measurements, and clinical findings. | Analytics, care-management, notification, and clinical decision-support platforms. | Martini preserves coding metadata and status, retrieves required patient or encounter context, and applies destination-specific privacy rules. |
| MedicationRequest | Medication orders and prescriptions, including status and effective-period information. | Care-management, patient-engagement, pharmacy-related, and clinical workflow systems. | Martini distinguishes read-only from approved write operations, preserves medication status and coding, and records source identifiers for reconciliation. |
Authentication and security considerations
OAuth 2.0 and SMART on FHIR
Epic application access generally uses OAuth 2.0 and SMART on FHIR patterns. Authorization-code, patient-context, and backend-services flows may be available depending on the application type and customer environment.
Scopes and credentials
Access is constrained by client registration, organization, patient context, permitted FHIR resources, and scopes such as patient, user, or system access. Store credentials, tokens, and private keys in Martini environment configuration or secrets rather than workflow definitions.
Healthcare privacy
- Apply minimum-necessary access and field-level filtering.
- Separate test and production credentials and endpoints.
- Protect PHI in transit, at rest, logs, and temporary processing areas.
- Use approved identity matching and preserve audit correlation.
Operational considerations for Epic integrations
Pagination and incremental retrieval
Follow FHIR server-provided next links and persist continuation state for long-running searches. Use supported incremental filters such as _lastUpdated only when the Epic implementation supports the required behavior.
Throttling and retries
Epic environments may impose request, concurrency, or operational limits. Use bounded concurrency, exponential backoff, Retry-After when supplied, and bulk APIs for large data volumes. Retry transient failures, not validation or authorization errors.
Identity and idempotency
Use FHIR resource IDs, business identifiers, message control IDs, and approved cross-reference tables. Do not rely on names and birth dates alone for patient matching, and design notifications and searches to tolerate duplicates.
Schema and testing
FHIR profiles, extensions, optional elements, local codes, and resource relationships vary by environment. Test representative resources, pagination, missing fields, terminology, write permissions, event gaps, document sizes, and reconciliation behavior.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration instead of scripts
Martini separates acquisition, transformation, business rules, delivery, and monitoring into maintainable workflows. This is useful when an Epic integration combines FHIR, bulk exports, HL7v2 messages, documents, and downstream APIs.
Reusable integration assets
Martini can expose controlled APIs, reuse authentication and transformation logic, and apply consistent mappings across Patient, Encounter, Appointment, Observation, and other Epic resources.
Operational control
Centralized error handling, checkpoints, retries, reconciliation, logging, and environment configuration reduce the operational risk of independently maintained scripts and point-to-point flows.
Frequently asked questions
Epic can be integrated through FHIR REST APIs, OAuth 2.0 and SMART on FHIR, asynchronous bulk exports, selected FHIR event notifications, customer-specific HL7v2 interfaces, and approved document or analytics access. The available resources, operations, events, and transport controls depend on the Epic customer environment.
Yes. Martini can consume Epic FHIR REST APIs, use configured OAuth 2.0 and SMART on FHIR authentication, orchestrate bulk and scheduled workflows, receive selected event notifications, process approved HL7v2 payloads, and expose normalized APIs for downstream applications.
No. A dedicated Epic connector is not required. Martini can integrate using Epic’s confirmed native mechanisms, including FHIR REST APIs, OAuth 2.0 and SMART on FHIR, selected notifications, bulk exports, HL7v2 interfaces, and approved document endpoints.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Epic. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Epic, the healthcare organization, cloud infrastructure, interface engines, or other third-party systems based on licensing, usage, and deployment arrangements.
FHIR REST APIs are generally appropriate for modern resource-oriented applications and SMART on FHIR experiences. HL7v2 is appropriate when the Epic customer provides interfaces for ADT, orders, results, scheduling, or other message workflows. Many enterprise designs use both.
Selected Epic environments may support FHIR Subscription or related event mechanisms, but coverage is partial and resource-specific. Martini can receive supported notifications, retrieve the current resource, and use scheduled polling or reconciliation when events are unavailable.
Martini can use FHIR searches with supported incremental filters, scheduled workflows, HL7v2 messages, bulk exports, or selected event notifications. Synchronization should follow server pagination, persist checkpoints, use stable identifiers for idempotency, and include reconciliation for missed or delayed changes.
Yes. Martini can expose a controlled API that normalizes approved Epic resources for downstream applications. The façade can centralize authentication, field mapping, business rules, patient-context controls, error handling, and access to only the Epic data each consumer is authorized to receive.
Related Martini documentation
API Consumption
Workflows
Events and Data
Connect Epic with Martini
Use Martini to orchestrate Epic FHIR, bulk, event, HL7v2, document, and approved analytics integrations through secure, maintainable workflows and APIs.