The EPIC EHR connector enables you to ingest clinical and administrative data from Epic's FHIR R4 API into Nexla data flows. Using pre-built endpoint templates for common FHIR resources—such as patients, observations, conditions, medications, and appointments—you can rapidly build data pipelines that extract structured healthcare data from any Epic organization. Follow the instructions below to create a new data flow that ingests data from an EPIC EHR source in Nexla.
Create a New Data Flow
-
To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.
-
Select the EPIC EHR connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Epic FHIR R4 API, and click Next; or, create a new EPIC EHR credential for use in this flow.
-
In Nexla, EPIC EHR data sources can be created using pre-built endpoint templates, which expedite source setup for common Epic FHIR R4 endpoints. Each template is designed specifically for the corresponding FHIR resource type, making source configuration easy and efficient.
• To configure this source using a template, follow the instructions in Configure Using a Template.
EPIC EHR sources can also be configured manually, allowing you to ingest data from Epic FHIR endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
• To configure this source manually, follow the instructions in Configure Manually.
Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Epic FHIR R4 resource endpoints. Each template is designed specifically for the corresponding FHIR resource, making data source setup easy and efficient.
Endpoint Settings
- Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.
Patient Search
Search for patients across the Epic organization by demographic criteria such as name, identifier, or birth date. Use this endpoint when you need to locate patient records or build patient lists based on demographic attributes. Results are paginated automatically using Epic's next-page link mechanism.
Additional information about the Epic Patient Search API is available at fhir.epic.com/Specifications?api=948. The response data path is $.entry[*].resource, meaning each FHIR Bundle entry's resource object becomes a separate record in Nexla.
Patient Read by ID
Retrieve a single, complete patient record by its Epic FHIR ID. Use this endpoint when you already know the unique FHIR identifier for a patient and need to retrieve their full demographic record.
- Patient FHIR ID (required): Enter the Epic FHIR patient ID (a UUID-format string assigned by Epic, e.g.,
eovIfYI9n-3iZzl5zvB.rGQ3). This ID can be obtained from a prior Patient Search or from an existing system that stores Epic FHIR IDs.
This endpoint returns a single FHIR Patient resource rather than a paginated bundle. The response data path is $, meaning the entire response is treated as one record.
Observation Search (Vitals & Labs)
Retrieve FHIR Observation resources for a patient, covering vital signs (blood pressure, heart rate, temperature, etc.) and laboratory results. This endpoint is commonly used to build clinical analytics pipelines that track patient health metrics over time.
Condition Search (Diagnoses)
Retrieve FHIR Condition resources representing patient diagnoses, chronic conditions, and problem list items. Use this endpoint to analyze diagnosis prevalence, track chronic conditions, or build population health dashboards.
Medication Request Search (Orders)
Retrieve FHIR MedicationRequest resources representing medication orders and prescriptions for a patient. Use this endpoint to analyze prescribing patterns, medication adherence, or to build clinical decision support pipelines.
Allergy Intolerance Search
Retrieve FHIR AllergyIntolerance resources documenting a patient's known allergies and intolerances, including the substance, reaction type, and severity. Use this endpoint to support medication safety workflows, population allergy analysis, or clinical data warehousing.
- Patient FHIR ID (required): Enter the Epic FHIR patient ID for the patient whose allergy records you want to retrieve.
- Page Size: Enter the number of results per page. Defaults to
50; maximum is 100.
Appointment Search
Retrieve FHIR Appointment resources representing scheduled visits for patients or practitioners. Use this endpoint to analyze scheduling patterns, calculate no-show rates, or build operational dashboards tracking appointment volumes.
- Patient FHIR ID (optional): Enter the Epic FHIR patient ID to retrieve appointments for a specific patient. Leave blank to retrieve appointments across all accessible patients.
- Date Range (optional): Enter a date range filter using FHIR prefix notation (e.g.,
ge2024-01-01 for appointments on or after January 1, 2024). - Page Size: Enter the number of results per page. Defaults to
50; maximum is 100.
Encounter Search (Visits)
Retrieve FHIR Encounter resources representing patient visits, including office visits, hospitalizations, emergency department encounters, and telehealth encounters. Use this endpoint to analyze care utilization, length of stay, or visit patterns across a patient population.
- Patient FHIR ID (required): Enter the Epic FHIR patient ID for the patient whose encounters you want to retrieve.
- Date Range (optional): Enter a date range filter using FHIR prefix notation (e.g.,
ge2023-01-01,le2023-12-31 for encounters within calendar year 2023). - Page Size: Enter the number of results per page. Defaults to
50; maximum is 100.
Diagnostic Report Search (Lab Results)
Retrieve FHIR DiagnosticReport resources containing finalized diagnostic results, including laboratory panel results, radiology reports, cardiology studies, and pathology reports. Use this endpoint to build clinical analytics pipelines focused on diagnostic outcomes.
Immunization Search
Retrieve FHIR Immunization resources documenting a patient's vaccination history, including vaccine type, administration date, dose number, and administering provider. Use this endpoint to support public health reporting, care gap analysis, or population health immunization tracking.
- This endpoint automatically retrieves all immunization records accessible for your application's patient population. No additional configuration parameters are required beyond selecting this endpoint template.
- Results are paginated automatically; Nexla will fetch all pages until the complete immunization history is retrieved.
Procedure Search
Retrieve FHIR Procedure resources representing clinical procedures and surgical interventions performed on patients, including procedure code, date, performer, and outcome. Use this endpoint to analyze procedural volumes, surgical outcomes, or care pathway adherence.
- This endpoint automatically retrieves all procedure records accessible for your application's patient population. No additional configuration parameters are required beyond selecting this endpoint template.
- Results are paginated automatically until all procedure records are retrieved.
Document Reference Search
Retrieve FHIR DocumentReference resources pointing to clinical documents, including physician notes, discharge summaries, operative reports, and other structured or unstructured clinical content. Use this endpoint to integrate narrative clinical documentation into downstream analytics or archival workflows.
- This endpoint retrieves all document references accessible to your application. No additional parameters are required beyond selecting this template.
- Each DocumentReference record contains metadata about the document (type, date, author) and a reference to the document content, which may be base64-encoded inline or provided as a URL.
Practitioner Search
Search for healthcare practitioners registered in the Epic organization by name or identifier. Use this endpoint to build provider directories, validate provider credentials, or enrich clinical data with practitioner details.
- Practitioner Name (optional): Enter a full or partial name to filter practitioners (e.g.,
Johnson). - NPI or Identifier (optional): Enter a National Provider Identifier (NPI) or another system identifier to locate a specific practitioner.
- Page Size: Enter the number of results per page. Defaults to
50; maximum is 100.
Practitioner Role Search
Retrieve FHIR PractitionerRole resources that describe a practitioner's role within an organization, including their specialty, department affiliation, location, and contact information. Use this endpoint to enrich provider directory data or support care team analysis.
- This endpoint retrieves all practitioner role records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically until all records are retrieved.
Organization Search
Search for healthcare organizations—including hospitals, clinics, and departments—registered in the Epic organization hierarchy. Use this endpoint to build facility directories, map care delivery locations, or enrich clinical data with organizational context.
- This endpoint retrieves all organization records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically.
Location Search
Retrieve FHIR Location resources representing physical care delivery locations, including exam rooms, nursing units, clinics, and hospital wards. Use this endpoint to map care delivery geography, track patient flow, or enrich encounter data with location details.
- This endpoint retrieves all location records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically.
Care Plan Search
Retrieve FHIR CarePlan resources documenting a patient's treatment plan, including planned activities, goals, and care team assignments. Use this endpoint to analyze care coordination, track treatment plan adherence, or build care management analytics.
- This endpoint retrieves all care plan records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically.
Goal Search
Retrieve FHIR Goal resources representing documented patient health goals and targeted outcomes, including goal descriptions, target measures, start dates, and achievement status. Use this endpoint to support value-based care analytics and population health goal tracking.
- This endpoint retrieves all goal records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically.
Care Team Search
Retrieve FHIR CareTeam resources identifying the members of a patient's care team, including primary care providers, specialists, care coordinators, and other clinical staff. Use this endpoint to analyze care team composition, track care coordination, or enrich clinical data with provider relationships.
- This endpoint retrieves all care team records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically.
Medication Statement Search
Retrieve FHIR MedicationStatement resources representing medications a patient is currently taking or has taken, including home medications and active prescriptions reported by the patient or their care team. Use this endpoint to build complete medication history profiles or analyze medication adherence.
- This endpoint retrieves all medication statement records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically.
Coverage Search (Insurance)
Retrieve FHIR Coverage resources representing a patient's insurance coverage information, including payer, plan, subscriber ID, and coverage period. Use this endpoint to support revenue cycle analytics, insurance verification workflows, or population payer mix analysis.
- This endpoint retrieves all coverage records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically.
Device Search (Implants)
Retrieve FHIR Device resources representing implanted or externally worn medical devices associated with patients, including pacemakers, insulin pumps, cochlear implants, and other tracked devices. Use this endpoint to support device registry analytics or post-market surveillance workflows.
- This endpoint retrieves all device records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically.
Service Request Search (Orders)
Retrieve FHIR ServiceRequest resources representing clinical orders placed in Epic, including laboratory orders, imaging orders, referrals, and procedure orders. Use this endpoint to analyze order volumes, turnaround times, or referral patterns.
- This endpoint retrieves all service request records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically.
Slot Search (Availability)
Retrieve FHIR Slot resources representing available appointment slots for scheduling within Epic. Use this endpoint to analyze scheduling capacity, identify availability gaps, or power online scheduling integrations.
- This endpoint retrieves all slot records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically.
Schedule Search
Retrieve FHIR Schedule resources representing practitioner and location schedules in Epic, including the actor (practitioner or location), specialty, and schedule dates. Use this endpoint to analyze provider availability or build scheduling analytics.
- This endpoint retrieves all schedule records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically.
Questionnaire Response Search
Retrieve FHIR QuestionnaireResponse resources containing patient responses to structured questionnaires, including patient-reported outcomes, screening assessments (PHQ-9, GAD-7, AUDIT-C, etc.), and intake forms. Use this endpoint to analyze patient-reported outcome data or build behavioral health analytics.
- This endpoint retrieves all questionnaire response records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically.
Family Member History Search
Retrieve FHIR FamilyMemberHistory resources documenting a patient's family health history, including conditions in biological relatives. Use this endpoint to support genetic risk analysis, hereditary disease screening, or population health risk stratification.
- This endpoint retrieves all family member history records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically.
Related Person Search
Retrieve FHIR RelatedPerson resources representing individuals related to a patient, such as emergency contacts, guardians, proxies, or MyChart proxy access holders. Use this endpoint to support care coordination, proxy access management, or patient engagement workflows.
- This endpoint retrieves all related person records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically.
Clinical Impression Search
Retrieve FHIR ClinicalImpression resources representing a clinician's assessment and clinical judgment about a patient's health status at a specific point in time. Use this endpoint to analyze clinical decision-making patterns or enrich encounter data with clinical assessments.
- This endpoint retrieves all clinical impression records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically.
Communication Search
Retrieve FHIR Communication resources representing messages, notifications, and alerts exchanged between care team members and patients within Epic, including MyChart messages. Use this endpoint to analyze patient-provider communication patterns or support care management workflows.
- This endpoint retrieves all communication records accessible to your application. No additional parameters are required beyond selecting this template.
- Results are paginated automatically.
Patient Summary (IPS)
Retrieve an International Patient Summary (IPS) document for a specific patient. The IPS is a standardized clinical document that consolidates a patient's most clinically relevant information—including problems, medications, allergies, and immunizations—into a single structured response. Use this endpoint for cross-border data exchange, care transitions, or population health summaries.
- Patient FHIR ID (required): Enter the Epic FHIR patient ID for the patient whose IPS summary you want to retrieve. The endpoint calls the FHIR
$summary operation on the Patient resource to generate the consolidated document. - This endpoint returns a single FHIR Bundle document rather than a paginated list. The full response bundle is captured as one record in Nexla.
Endpoint Testing
Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.
-
To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.
-
If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.
EPIC EHR data sources can be manually configured to ingest data from any valid Epic FHIR R4 API endpoint. Manual configuration provides maximum flexibility for accessing FHIR resource types or operations not covered by pre-built templates, or when you need custom query parameters and API configurations.
With manual configuration, you can also create more advanced EPIC EHR sources—such as sources that chain multiple FHIR API calls, use date range macros to incrementally ingest data, or apply custom request headers for specific Epic organization requirements.
API Method
-
To manually configure this source, select the Advanced tab at the top of the configuration screen.
-
Select the API method that will be used for calls to the Epic FHIR R4 API from the Method pulldown menu. The most common method is:
- GET: For retrieving FHIR resources from the API (used for all standard FHIR read and search operations).
API Endpoint URL
-
Enter the URL of the Epic FHIR R4 API endpoint from which this source will fetch data in the Set API URL field. This should be the complete URL, including the FHIR base URL and resource type path. For example:
- Patient search:
https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/Patient
- Observation search with parameters:
https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/Observation?patient=<FHIR_ID>&category=laboratory
- Patient read:
https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/Patient/<FHIR_ID>
Replace the FHIR base URL portion with the base URL for your target Epic organization. For production integrations, the base URL is provided by the Epic customer's integration team.
Date/Time Macros (API URL)
Optional
Optionally, the API URL can be customized using macros—all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that adapt to different time periods or incremental data requirements. This is particularly useful for Epic FHIR endpoints that accept date parameters (such as date=, _lastUpdated=, or similar search parameters).
Date/time macros are especially useful for Epic FHIR APIs that support incremental data extraction. For example, you can use {now-1} with a daily schedule to pull only the observations recorded in the last day.
-
To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.
{now} – The current datetime{now-1} – The datetime one time unit before the current datetime{now+1} – The datetime one time unit after the current datetimecustom – Datetime macros can reference any number of time units before or after the current datetime—for example, enter (now-4) to indicate the datetime four time units before the current datetime
-
Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. This format will be applied to the base datetime value of the macro—i.e., the value of {now} in {now-1}.
-
Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu—for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.
Lookup-Based Macros (API URL)
Optional
Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic Epic FHIR API endpoints that adapt based on existing data—for example, using a list of patient FHIR IDs from a prior source to drive per-patient FHIR queries.
Lookup-based macros are useful when you need to create Epic FHIR API endpoints that reference specific patient IDs, encounter IDs, or other identifiers retrieved from other data sources in your Nexla environment.
-
To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.
-
Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.
Epic FHIR search responses are returned as FHIR Bundle resources that contain an entry array, where each element holds a resource object with the actual clinical data. By specifying the path to the relevant data, you configure Nexla to extract individual resources rather than treating the entire Bundle as a single record.
Path to Data is important for Epic FHIR search responses. For most FHIR search endpoints, the correct JSON path is $.entry[*].resource, which extracts each FHIR resource from the Bundle entry array as a separate record. For FHIR read operations (single resource), the path $ treats the entire response as one record.
Autogenerate Path Suggestions
Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.
-
To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.
-
Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.
If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. For Epic FHIR responses, this is useful when you want to preserve Bundle-level metadata (such as total count or search links) alongside each extracted resource record.
-
If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2). For Epic FHIR APIs, a common additional header is Content-Type:application/json+fhir or Accept:application/fhir+json for FHIR-specific content negotiation.
You do not need to include authorization headers—these are managed automatically by Nexla using the configured EPIC EHR credential. The Content-Type:application/json+fhir header is already included in the pre-built endpoint templates.
Endpoint Testing
After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.
-
To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.
-
If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.
Save & Activate the Source
- Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new EPIC EHR data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.
