Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Epic

Scalekit connector
Open markdown

The Epic connector lets your AI agent act in each user's Epic account. Each user signs in to Epic once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 53 tools.

Tools
53
What they doRead · write · destructive
47 · 6 · 047 read6 write0 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Epic connection

    In AgentKit > Connections, create an Epic connection. The name you give it is the connection_name your code passes. See Configure connections.

    Console steps with screenshots

    Epic connections use SMART on FHIR and act as the signed-in clinician. Every health system runs its own Epic FHIR server, so each connection carries that server’s authorization endpoint, token endpoint, audience (aud) and FHIR server domain, plus the client ID and secret of your Epic app.

    1. Create the connection and copy the redirect URI

      In the Scalekit dashboard, go to AgentKit > Connections > Create Connection, find Epic and click Create. Copy the Redirect URI.

    2. Register a clinician-facing app with Epic

      Register a confidential app for clinicians or providers with Epic, and note its client ID and client secret:

      • Add the redirect URI you copied as a redirect URI.
      • Request refresh tokens, so Scalekit can refresh the clinician’s access (offline_access).
      • Click Generate Secret, copy the secret, then click Store Hash before you save the app. Epic shows the secret only once, and keeps only its hash. Enter the secret itself in Scalekit, not the hash.
      • Select the Epic APIs your agent calls. Epic grants only the scopes that match the APIs on the app.
      • To book appointments, also select the STU3 Appointment.$find, Appointment.$book, Slot.Read and Schedule.Read APIs.

      A new sandbox app can take about an hour to become usable. Once you mark an app ready for production, Epic no longer lets you edit its scopes or redirect URI.

    3. Find the health system’s Epic endpoints

      Each health system lists its Epic FHIR base URL in Epic’s endpoint directory. The FHIR R4 base ends in /api/FHIR/R4, for example https://<host>/<instance>/api/FHIR/R4. Open <R4 base>/.well-known/smart-configuration and copy authorization_endpoint and token_endpoint.

    4. Enter the values on the connection

      Back on the Epic connection, enter:

      • Client ID and Client Secret: from your Epic app.
      • Authorization Endpoint and Token Endpoint: from .well-known/smart-configuration.
      • Audience (aud): the full R4 base URL, ending in /api/FHIR/R4.
      • FHIR Server Domain: the same address without https://, ending at /api/FHIR. Leave off /R4: the tools add /R4, and the scheduling tools add /STU3, because Epic offers scheduling only in FHIR STU3.

      Select openid, fhirUser and offline_access, plus the resource scopes your agent needs, such as user/Patient.read. Use one scope style, SMART v1 (.read, .write) or SMART v2 (.rs, .c), to match your Epic app. Click Save.

      To test against Epic’s sandbox, use these values:

      FieldSandbox value
      Authorization Endpointhttps://fhir.epic.com/interconnect-fhir-oauth/oauth2/authorize
      Token Endpointhttps://fhir.epic.com/interconnect-fhir-oauth/oauth2/token
      Audience (aud)https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4
      FHIR Server Domainfhir.epic.com/interconnect-fhir-oauth/api/FHIR

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • epic_allergy_intolerance_readGet one AllergyIntolerance resource from Epic by its FHIR ID.Read-only

    Get Allergy

    Get one AllergyIntolerance resource from Epic by its FHIR ID. Returns the AllergyIntolerance resource: substance code, clinical and verification status, type, category, criticality, reactions and onset. Use this when you already have the AllergyIntolerance ID. Use epic_allergy_intolerance_search to list a patient's allergies.

    Inputs

    allergy_intolerance_idstringrequired
    FHIR logical ID of the AllergyIntolerance resource to retrieve, as returned in the id field of a AllergyIntolerance search result or in a reference such as AllergyIntolerance/<id>. Example: 12345.
  • epic_appointment_find_slotsFind open appointment times in Epic for a visit type, within an optional time window and with optional patient details ($find, STU3).Read-only

    Find Appointment Slots

    Find open appointment times in Epic for a visit type, within an optional time window and with optional patient details ($find, STU3). Returns a searchset Bundle of proposed Appointment resources (status proposed, start, end, minutesDuration, serviceType, participants for the provider and department, and the held Slot as a contained resource). Only the first page is returned (10 by default); epic_next_page cannot page these results. Use this to offer bookable times, then epic_appointment_book with the chosen entry's id. Use epic_appointment_search for appointments a patient already has. The health system must have built Epic scheduling rules for this app; those rules decide which inputs are used or required and which slots come back.

    Inputs

    service_type_codestringrequired
    Code of the visit type (Epic visit type) to find slots for. Visit type codes are set up by each health system. Example: 12345.
    service_type_systemstringrequired
    Code system of the visit type code, usually the health system's visit type OID. Example: urn:oid:1.2.840.114350.1.13.0.1.7.3.808267.11.
    days_of_weekarray
    Days of the week to search, as FHIR day codes. Example: ["tue", "thu"].
    durationnumber
    Appointment duration, in the unit given by Duration Unit. Example: 30.
    duration_unitstring
    Unit of Duration: s (seconds), min (minutes), h (hours) or d (days).one of sminhd
    end_timestring
    Latest end of the slots to search, as a FHIR dateTime with time zone. Example: 2024-05-05T22:00:00Z.
    indication_codingsarray
    Diagnosis codes the visit is for, each with system, code and optional display. Epic accepts a community diagnosis code and/or a SNOMED code; if both are sent, the community diagnosis code wins. Example: [{"system": "urn:oid:2.16.840.1.113883.6.96", "code": "46866001", "display": "Fracture of lower limb"}].
    indication_textstring
    Plain-text description of the diagnosis indications. Example: Broken leg.
    location_referencestring
    Reference to the Location (department) to search in, as Location/<FHIR ID> or the full STU3 Location URL. Example: Location/12345.
    patient_address_linearray
    Street lines of the patient's home address. Example: ["123 Main St"].
    patient_birth_datestring
    Patient's date of birth as YYYY-MM-DD. Example: 1980-01-01.
    patient_citystring
    City of the patient's home address. Example: Madison.
    patient_countrystring
    Country of the patient's home address. Example: US.
    patient_districtstring
    County of the patient's home address. Example: Dane.
    patient_emailstring
    Patient's email address. Example: patient@example.com.
    patient_familystring
    Patient's family (last) name, used by the health system's scheduling rules. Example: Testpatient.
    patient_genderstring
    Patient's legal sex as a FHIR gender code: male, female, other or unknown.one of malefemaleotherunknown
    patient_givenarray
    Patient's given names (first, then middle). Example: ["Jane"].
    patient_identifier_systemstring
    System of a patient identifier, such as the health system's MRN OID. Send together with Patient Identifier Value. Example: urn:oid:1.2.3.4.
    patient_identifier_valuestring
    Value of the identifier named by Patient Identifier System, such as the MRN. Example: 12345.
    patient_name_usestring
    Kind of name sent: usual or official.one of usualofficial
    patient_phonestring
    Patient's phone number. Example: 555-555-0100.
    patient_phone_usestring
    Kind of phone number: home, mobile or work.one of homemobilework
    patient_postal_codestring
    ZIP code of the patient's home address, as nnnnn or nnnnn-nnnn. Example: 53703.
    patient_statestring
    State of the patient's home address, as a two-letter postal code. Example: WI.
    patient_temporary_countrystring
    Country of the patient's temporary address. Example: US.
    patient_temporary_statestring
    State of the patient's temporary address (where the patient is now, if different from home), as a two-letter postal code. Example: IL.
    patient_timezonestring
    Patient's time zone, as an IANA time zone name. Example: America/Chicago.
    referral_idstring
    Referral ID; Epic uses the referral to pick the right visit type and providers. Example: 12345.
    referral_systemstring
    Code system of the referral ID, if the health system uses one. Example: urn:oid:1.2.3.4.
    service_type_displaystring
    Display name of the visit type. Example: Office Visit.
    specialty_codestring
    Department specialty code to limit slots to. Example: 12345.
    specialty_displaystring
    Display name of the specialty. Example: Gastroenterology.
    specialty_systemstring
    Code system of the specialty code, usually a health-system OID. Example: urn:oid:1.2.3.4.
    start_timestring
    Earliest start of the slots to search, as a FHIR dateTime with time zone. Example: 2024-05-01T13:00:00Z.
    times_of_dayarray
    Preferred times of day for the appointment, as HH:MM:SS. Example: ["09:00:00"].
  • epic_appointment_readGet one Appointment resource from Epic by its FHIR ID.Read-only

    Get Appointment

    Get one Appointment resource from Epic by its FHIR ID. Returns the Appointment resource: status, serviceType, appointmentType, start and end times, participants (patient, practitioner, location) and comments. Use this when you already have the Appointment ID. Use epic_appointment_search to list a patient's appointments.

    Inputs

    appointment_idstringrequired
    FHIR logical ID of the Appointment resource to retrieve, as returned in the id field of a Appointment search result or in a reference such as Appointment/<id>. Example: 12345.
  • epic_binary_readGet a Binary resource from Epic by its FHIR ID, such as the HTML or RTF text of a clinical note.Read-only

    Get Binary

    Get a Binary resource from Epic by its FHIR ID, such as the HTML or RTF text of a clinical note. Returns a Binary resource with contentType and base64-encoded data. Use this after epic_document_reference_search or epic_document_reference_read: take the Binary ID from content[].attachment.url (Binary/<id>).

    Inputs

    binary_idstringrequired
    FHIR ID of the Binary resource, from the end of a DocumentReference attachment URL (Binary/<id>). Example: 12345.
  • epic_care_plan_readGet one CarePlan resource from Epic by its FHIR ID.Read-only

    Get Care Plan

    Get one CarePlan resource from Epic by its FHIR ID. Returns the CarePlan resource: category, status, intent, period, activities, goals and addresses (conditions). Use this when you already have the CarePlan ID. Use epic_care_plan_search to list a patient's care plans.

    Inputs

    care_plan_idstringrequired
    FHIR logical ID of the CarePlan resource to retrieve, as returned in the id field of a CarePlan search result or in a reference such as CarePlan/<id>. Example: 12345.
All 16 in Healthcare & life sciences