> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns. > > **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal): > ```bash > npx -y @scalekit-inc/cli setup -y > ``` > > Global: > ```bash > npm install -g @scalekit-inc/cli > scalekit setup -y > ``` > > Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`. > Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim. > [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # Connect AI agents to Epic 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. **Authentication:** SMART On FHIR **Categories:** Healthcare **Tools:** 53: 47 read, 6 write, 0 destructive **Users sign in with:** SMART on FHIR **Built by:** Scalekit connector **Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=EPIC) ## Setup 1. ### Install the SDK **Node.js** ```bash npm install @scalekit-sdk/node dotenv ``` **Python** ```bash pip install scalekit-sdk-python python-dotenv ``` 2. ### Set your credentials Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**. ```sh title=".env" SCALEKIT_ENVIRONMENT_URL= SCALEKIT_CLIENT_ID= SCALEKIT_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](/agentkit/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](https://app.scalekit.com), 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](https://open.epic.com/MyApps/Endpoints). The FHIR R4 base ends in `/api/FHIR/R4`, for example `https:////api/FHIR/R4`. Open `/.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: | Field | Sandbox value | | ---------------------- | ----------------------------------------------------------------- | | Authorization Endpoint | `https://fhir.epic.com/interconnect-fhir-oauth/oauth2/authorize` | | Token Endpoint | `https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token` | | Audience (aud) | `https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4` | | FHIR Server Domain | `fhir.epic.com/interconnect-fhir-oauth/api/FHIR` | > caution: Each health system activates your app > > Before clinicians at a health system can sign in, that health system's Epic administrators must activate your app for production. Appointment booking also needs the health system to set up scheduling for your app; until it does, `epic_appointment_find_slots` returns an OperationOutcome such as "unable to determine a Visit Type". ## Tools Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool). **Node.js** ```typescript const result = await actions.executeTool({ toolName: 'epic_allergy_intolerance_read', toolInput: { allergy_intolerance_id: '', }, connector: 'epic', identifier: 'user_123', }) ``` **Python** ```python result = actions.execute_tool( tool_name="epic_allergy_intolerance_read", tool_input={ "allergy_intolerance_id": "", }, connection_name="epic", identifier="user_123", ) ``` `result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call. ### `epic_allergy_intolerance_read` Get Allergy · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `allergy_intolerance_id` (`string`, required): 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/. Example: 12345. Example input: `{"allergy_intolerance_id":""}` ### `epic_allergy_intolerance_search` Search Allergies · Read-only Search a patient's allergies and intolerances in Epic, optionally filtered by status, category, criticality or code. Returns a FHIR searchset Bundle whose entry array holds matching AllergyIntolerance resources (substance, clinicalStatus, verificationStatus, category, criticality and reaction) and a 'next' link when more pages exist. Use this to review a patient's allergy list. Use epic_allergy_intolerance_read for one allergy by ID. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `patient_id` (`string`, required): FHIR ID of the patient whose allergies to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `_count` (`integer`, optional): Maximum number of results Epic returns in one page of the search Bundle. When more results exist, the Bundle's link array has a 'next' URL. Example: 20. - `category` (`string`, optional): Allergy category: food, medication, environment or biologic (organizations may configure more). - `clinical_status` (`string`, optional): Return only allergies with this clinical status. Epic accepts only 'active'; leave blank to return active and resolved allergies. One of: `active`. - `code` (`string`, optional): Code of the allergen, as | or just . Example: http://www.nlm.nih.gov/research/umls/rxnorm|7980. - `criticality` (`string`, optional): Risk of clinical harm: low, high or unable-to-assess. One of: `low`, `high`, `unable-to-assess`. - `date` (`string`, optional): Filter by the date the allergy was recorded in Epic. Use a FHIR date (YYYY-MM-DD) or dateTime, optionally with a prefix such as ge (on or after), le (on or before), gt or lt. Example: ge2024-01-01. - `severity` (`string`, optional): Severity of the patient's reaction: mild, moderate or severe. One of: `mild`, `moderate`, `severe`. - `type` (`string`, optional): Underlying mechanism: allergy or intolerance. One of: `allergy`, `intolerance`. Example input: `{"patient_id":""}` ### `epic_appointment_find_slots` Find Appointment Slots · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `service_type_code` (`string`, required): 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_system` (`string`, required): 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_week` (`array`, optional): Days of the week to search, as FHIR day codes. Example: ["tue", "thu"]. - `duration` (`number`, optional): Appointment duration, in the unit given by Duration Unit. Example: 30. - `duration_unit` (`string`, optional): Unit of Duration: s (seconds), min (minutes), h (hours) or d (days). One of: `s`, `min`, `h`, `d`. - `end_time` (`string`, optional): Latest end of the slots to search, as a FHIR dateTime with time zone. Example: 2024-05-05T22:00:00Z. - `indication_codings` (`array`, optional): 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_text` (`string`, optional): Plain-text description of the diagnosis indications. Example: Broken leg. - `location_reference` (`string`, optional): Reference to the Location (department) to search in, as Location/ or the full STU3 Location URL. Example: Location/12345. - `patient_address_line` (`array`, optional): Street lines of the patient's home address. Example: ["123 Main St"]. - `patient_birth_date` (`string`, optional): Patient's date of birth as YYYY-MM-DD. Example: 1980-01-01. - `patient_city` (`string`, optional): City of the patient's home address. Example: Madison. - `patient_country` (`string`, optional): Country of the patient's home address. Example: US. - `patient_district` (`string`, optional): County of the patient's home address. Example: Dane. - `patient_email` (`string`, optional): Patient's email address. Example: patient@example.com. - `patient_family` (`string`, optional): Patient's family (last) name, used by the health system's scheduling rules. Example: Testpatient. - `patient_gender` (`string`, optional): Patient's legal sex as a FHIR gender code: male, female, other or unknown. One of: `male`, `female`, `other`, `unknown`. - `patient_given` (`array`, optional): Patient's given names (first, then middle). Example: ["Jane"]. - `patient_identifier_system` (`string`, optional): 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_value` (`string`, optional): Value of the identifier named by Patient Identifier System, such as the MRN. Example: 12345. - `patient_name_use` (`string`, optional): Kind of name sent: usual or official. One of: `usual`, `official`. - `patient_phone` (`string`, optional): Patient's phone number. Example: 555-555-0100. - `patient_phone_use` (`string`, optional): Kind of phone number: home, mobile or work. One of: `home`, `mobile`, `work`. - `patient_postal_code` (`string`, optional): ZIP code of the patient's home address, as nnnnn or nnnnn-nnnn. Example: 53703. - `patient_state` (`string`, optional): State of the patient's home address, as a two-letter postal code. Example: WI. - `patient_temporary_country` (`string`, optional): Country of the patient's temporary address. Example: US. - `patient_temporary_state` (`string`, optional): 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_timezone` (`string`, optional): Patient's time zone, as an IANA time zone name. Example: America/Chicago. - `referral_id` (`string`, optional): Referral ID; Epic uses the referral to pick the right visit type and providers. Example: 12345. - `referral_system` (`string`, optional): Code system of the referral ID, if the health system uses one. Example: urn:oid:1.2.3.4. - `service_type_display` (`string`, optional): Display name of the visit type. Example: Office Visit. - `specialty_code` (`string`, optional): Department specialty code to limit slots to. Example: 12345. - `specialty_display` (`string`, optional): Display name of the specialty. Example: Gastroenterology. - `specialty_system` (`string`, optional): Code system of the specialty code, usually a health-system OID. Example: urn:oid:1.2.3.4. - `start_time` (`string`, optional): Earliest start of the slots to search, as a FHIR dateTime with time zone. Example: 2024-05-01T13:00:00Z. - `times_of_day` (`array`, optional): Preferred times of day for the appointment, as HH:MM:SS. Example: ["09:00:00"]. Example input: `{"service_type_code":"","service_type_system":""}` ### `epic_appointment_read` Get Appointment · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `appointment_id` (`string`, required): 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/. Example: 12345. Example input: `{"appointment_id":""}` ### `epic_appointment_search` Search Appointments · Read-only Search a patient's scheduled appointments or surgeries in Epic, optionally by date or status. Returns a FHIR searchset Bundle whose entry array holds matching Appointment resources (status, start, end, serviceType, appointmentType and participant) and a 'next' link when more pages exist. Set Service Category to appointment for visits or surgery for scheduled surgeries. Use epic_encounter_search for visits that already happened. Use epic_appointment_read for one appointment by ID. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `patient_id` (`string`, required): FHIR ID of the patient whose appointments to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `date` (`string`, optional): Filter by the appointment date. Use a FHIR date (YYYY-MM-DD) or dateTime, optionally with a prefix such as ge (on or after), le (on or before), gt or lt. Example: ge2024-01-01. - `identifier` (`string`, optional): Appointment identifier (the encounter CSN) as | or . Example: 12345. - `service_category` (`string`, optional): Kind of appointment to return: appointment (regular visits) or surgery (scheduled surgeries). One of: `appointment`, `surgery`. - `status` (`string`, optional): Appointment status, such as booked, arrived, fulfilled, cancelled, noshow or proposed. Example input: `{"patient_id":""}` ### `epic_binary_read` Get Binary · Read-only 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/). Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `binary_id` (`string`, required): FHIR ID of the Binary resource, from the end of a DocumentReference attachment URL (Binary/). Example: 12345. Example input: `{"binary_id":""}` ### `epic_care_plan_read` Get Care Plan · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `care_plan_id` (`string`, required): 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/. Example: 12345. Example input: `{"care_plan_id":""}` ### `epic_care_plan_search` Search Care Plans · Read-only Search a patient's care plans in Epic by category. Returns a FHIR searchset Bundle whose entry array holds matching CarePlan resources (category, status, intent, period, activity and goal references) and a 'next' link when more pages exist. Use this to see the plan of care. Use epic_goal_search for the goals themselves. Use epic_care_plan_read for one care plan by ID. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `category` (`string`, required): Type of care plan (required by Epic). Use 38717003 for longitudinal care plans or 734163000 for encounter-level care plans; other Epic care plan types have their own codes. - `patient_id` (`string`, required): FHIR ID of the patient whose care plans to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `encounter` (`string`, optional): FHIR ID of an Encounter, for encounter-level care plans (category 734163000). Example: 12345. Example input: `{"category":"","patient_id":""}` ### `epic_care_team_read` Get Care Team · Read-only Get one CareTeam resource from Epic by its FHIR ID. Returns the CareTeam resource: status, category, participants with their roles, and period. Use this when you already have the CareTeam ID. Use epic_care_team_search to find a patient's care team. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `care_team_id` (`string`, required): FHIR logical ID of the CareTeam resource to retrieve, as returned in the id field of a CareTeam search result or in a reference such as CareTeam/. Example: 12345. Example input: `{"care_team_id":""}` ### `epic_care_team_search` Search Care Teams · Read-only Search a patient's longitudinal care team in Epic. Returns a FHIR searchset Bundle whose entry array holds matching CareTeam resources (status, participant members and roles) and a 'next' link when more pages exist. Use this to see who is on a patient's care team. Use epic_practitioner_read to resolve a member. Use epic_care_team_read for one care team by ID. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `patient_id` (`string`, required): FHIR ID of the patient whose care team to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `_count` (`integer`, optional): Maximum number of results Epic returns in one page of the search Bundle. When more results exist, the Bundle's link array has a 'next' URL. Example: 20. - `category` (`string`, optional): Type of team. Epic supports only longitudinal. One of: `longitudinal`. - `status` (`string`, optional): Care team status. Epic supports only active. One of: `active`. Example input: `{"patient_id":""}` ### `epic_condition_read` Get Condition · Read-only Get one Condition resource from Epic by its FHIR ID. Returns the Condition resource: code (ICD-10/SNOMED), category, clinical and verification status, onset, abatement and notes. Use this when you already have the Condition ID. Use epic_condition_search to list a patient's problems or encounter diagnoses. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `condition_id` (`string`, required): FHIR logical ID of the Condition resource to retrieve, as returned in the id field of a Condition search result or in a reference such as Condition/. Example: 12345. Example input: `{"condition_id":""}` ### `epic_condition_search` Search Conditions · Read-only Search a patient's conditions in Epic: problem list items, encounter diagnoses, health concerns and other categories. Returns a FHIR searchset Bundle whose entry array holds matching Condition resources (code, category, clinicalStatus, verificationStatus, onset and recordedDate) and a 'next' link when more pages exist. Use this to review the problem list (category problem-list-item) or a visit's diagnoses (category encounter-diagnosis with an encounter). Use epic_condition_read for one condition by ID. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `patient_id` (`string`, required): FHIR ID of the patient whose conditions to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `_count` (`integer`, optional): Maximum number of results Epic returns in one page of the search Bundle. When more results exist, the Bundle's link array has a 'next' URL. Example: 20. - `category` (`string`, optional): Which kind of condition to return. Common Epic values: problem-list-item, encounter-diagnosis, health-concern, medical-history, reason-for-visit. Leave blank for Epic's default (problem list). - `clinical_status` (`string`, optional): Clinical status: active, resolved or inactive (deleted problems). One of: `active`, `resolved`, `inactive`. - `code` (`string`, optional): Code of the condition, as | or just . Example: http://hl7.org/fhir/sid/icd-10-cm|E11.9. - `encounter` (`string`, optional): FHIR ID of an Encounter, to return the diagnoses filed on that visit (use with category encounter-diagnosis). Example: 12345. - `onset_date` (`string`, optional): Filter by the date the condition was noted. Use a FHIR date (YYYY-MM-DD) or dateTime, optionally with a prefix such as ge (on or after), le (on or before), gt or lt. Example: ge2024-01-01. - `recorded_date` (`string`, optional): Filter by the date the condition was recorded. Use a FHIR date (YYYY-MM-DD) or dateTime, optionally with a prefix such as ge (on or after), le (on or before), gt or lt. Example: ge2024-01-01. Example input: `{"patient_id":""}` ### `epic_coverage_read` Get Coverage · Read-only Get one Coverage resource from Epic by its FHIR ID. Returns the Coverage resource: status, type, subscriber, beneficiary, relationship, period, payor and class (group and plan). Use this when you already have the Coverage ID. Use epic_coverage_search to list a patient's insurance coverages. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `coverage_id` (`string`, required): FHIR logical ID of the Coverage resource to retrieve, as returned in the id field of a Coverage search result or in a reference such as Coverage/. Example: 12345. Example input: `{"coverage_id":""}` ### `epic_coverage_search` Search Coverages · Read-only Search a patient's insurance coverages in Epic. Returns a FHIR searchset Bundle whose entry array holds matching Coverage resources (status, type, subscriber, beneficiary, payor, period and class) and a 'next' link when more pages exist. Use this to check insurance on file. Use epic_organization_read to resolve a payor reference. Use epic_coverage_read for one coverage by ID. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `patient_id` (`string`, required): FHIR ID of the patient whose coverages to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `_count` (`integer`, optional): Maximum number of results Epic returns in one page of the search Bundle. When more results exist, the Bundle's link array has a 'next' URL. Example: 20. Example input: `{"patient_id":""}` ### `epic_diagnostic_report_read` Get Diagnostic Report · Read-only Get one DiagnosticReport resource from Epic by its FHIR ID. Returns the DiagnosticReport resource: code, category, status, effective time, issued time, result Observation references, conclusion and presentedForm. Use this when you already have the DiagnosticReport ID. Use epic_diagnostic_report_search to list a patient's reports. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `diagnostic_report_id` (`string`, required): FHIR logical ID of the DiagnosticReport resource to retrieve, as returned in the id field of a DiagnosticReport search result or in a reference such as DiagnosticReport/. Example: 12345. Example input: `{"diagnostic_report_id":""}` ### `epic_diagnostic_report_search` Search Diagnostic Reports · Read-only Search a patient's diagnostic reports in Epic: lab panels, imaging, pathology and cardiology results. Returns a FHIR searchset Bundle whose entry array holds matching DiagnosticReport resources (code, category, status, effectiveDateTime, issued and result references) and a 'next' link when more pages exist. Use this for whole reports. Use epic_observation_search for individual result values. Use epic_diagnostic_report_read for one report by ID. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `patient_id` (`string`, required): FHIR ID of the patient whose reports to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `_count` (`integer`, optional): Maximum number of results Epic returns in one page of the search Bundle. When more results exist, the Bundle's link array has a 'next' URL. Example: 20. - `category` (`string`, optional): Report category, with or without a system. Supported: LAB (system http://terminology.hl7.org/CodeSystem/v2-0074), or LOINC LP29684-5 radiology, LP7839-6 pathology, LP29708-2 cardiology. Example: LAB. - `code` (`string`, optional): Code of the report (LOINC, CPT, SNOMED or another code mapped to the procedure), as | or . Example: http://loinc.org|24323-8. - `date` (`string`, optional): Filter by the clinically relevant time of the report. Use a FHIR date (YYYY-MM-DD) or dateTime, optionally with a prefix such as ge (on or after), le (on or before), gt or lt. Example: ge2024-01-01. - `encounter` (`string`, optional): FHIR ID of the Encounter the report belongs to. Example: 12345. - `issued` (`string`, optional): Filter by when the report was issued. Use a FHIR date (YYYY-MM-DD) or dateTime, optionally with a prefix such as ge (on or after), le (on or before), gt or lt. Example: ge2024-01-01. Example input: `{"patient_id":""}` ### `epic_document_reference_read` Get Document · Read-only Get one DocumentReference resource from Epic by its FHIR ID. Returns the DocumentReference resource: type, category, docStatus, date, author, encounter context and content attachments (Binary URLs for HTML/RTF note text). Use this when you already have the DocumentReference ID. Use epic_document_reference_search to list notes, then epic_binary_read to get the note text. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `document_reference_id` (`string`, required): FHIR logical ID of the DocumentReference resource to retrieve, as returned in the id field of a DocumentReference search result or in a reference such as DocumentReference/. Example: 12345. Example input: `{"document_reference_id":""}` ### `epic_document_reference_search` Search Documents · Read-only Search a patient's documents in Epic, such as clinical notes, filtered by category, note type, date, status or encounter. Returns a FHIR searchset Bundle whose entry array holds matching DocumentReference resources (type, category, docStatus, date, author, context.encounter and content[].attachment.url) and a 'next' link when more pages exist. Set Category to clinical-note to return clinical notes only. Use epic_binary_read with an attachment URL's Binary ID to read the note text. Use epic_document_reference_read for one document by ID. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `patient_id` (`string`, required): FHIR ID of the patient whose documents to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `_count` (`integer`, optional): Maximum number of results Epic returns in one page of the search Bundle. When more results exist, the Bundle's link array has a 'next' URL. Example: 20. - `category` (`string`, optional): Document category. Use clinical-note to return only clinical notes. - `date` (`string`, optional): Filter by when the note was created. Use a FHIR date (YYYY-MM-DD) or dateTime, optionally with a prefix such as ge (on or after), le (on or before), gt or lt. Example: ge2024-01-01. - `docstatus` (`string`, optional): Note status: preliminary (unsigned draft), final (signed), amended or entered-in-error. One of: `preliminary`, `final`, `amended`, `entered-in-error`. - `encounter` (`string`, optional): FHIR ID of the Encounter the note belongs to. Example: 12345. - `type` (`string`, optional): Note type as |, usually a LOINC note code such as http://loinc.org|11506-3 (progress note). Example: http://loinc.org|11506-3. Example input: `{"patient_id":""}` ### `epic_encounter_read` Get Encounter · Read-only Get one Encounter resource from Epic by its FHIR ID. Returns the Encounter resource: status, class, type, period, participants, location, reason and hospitalization details. Use this when you already have the Encounter ID. Use epic_encounter_search to list a patient's visits. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `encounter_id` (`string`, required): FHIR logical ID of the Encounter resource to retrieve, as returned in the id field of a Encounter search result or in a reference such as Encounter/. Example: 12345. Example input: `{"encounter_id":""}` ### `epic_encounter_search` Search Encounters · Read-only Search a patient's encounters (office visits, admissions, telehealth and other contacts) in Epic. Returns a FHIR searchset Bundle whose entry array holds matching Encounter resources (status, class, type, period, participant, location and reasonCode) and a 'next' link when more pages exist. Use this to find a visit, for example the open encounter needed by epic_observation_create or epic_document_reference_create. Use epic_appointment_search for scheduled future visits. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `patient_id` (`string`, required): FHIR ID of the patient whose encounters to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `_count` (`integer`, optional): Maximum number of results Epic returns in one page of the search Bundle. When more results exist, the Bundle's link array has a 'next' URL. Example: 20. - `date` (`string`, optional): Filter by the date range the encounter takes place in. Use a FHIR date (YYYY-MM-DD) or dateTime, optionally with a prefix such as ge (on or after), le (on or before), gt or lt. Example: ge2024-01-01. - `practitioner` (`string`, optional): FHIR ID of a Practitioner who took part in the encounter. Example: 12345. - `status` (`string`, optional): Encounter status, such as planned, arrived, in-progress, finished or cancelled. Example input: `{"patient_id":""}` ### `epic_goal_read` Get Goal · Read-only Get one Goal resource from Epic by its FHIR ID. Returns the Goal resource: description, lifecycleStatus, achievementStatus, category, target and start date. Use this when you already have the Goal ID. Use epic_goal_search to list a patient's goals. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `goal_id` (`string`, required): FHIR logical ID of the Goal resource to retrieve, as returned in the id field of a Goal search result or in a reference such as Goal/. Example: 12345. Example input: `{"goal_id":""}` ### `epic_goal_search` Search Goals · Read-only Search a patient's care goals in Epic. Returns a FHIR searchset Bundle whose entry array holds matching Goal resources (description, lifecycleStatus, category, target and startDate) and a 'next' link when more pages exist. Use this to review treatment goals. Use epic_care_plan_search for the plans that hold them. Use epic_goal_read for one goal by ID. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `patient_id` (`string`, required): FHIR ID of the patient whose goals to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `category` (`string`, optional): Goal category, such as treatment, dietary or behavioral. Leave blank for all goals. - `lifecycle_status` (`string`, optional): Goal status: active, completed or cancelled. One of: `active`, `completed`, `cancelled`. Example input: `{"patient_id":""}` ### `epic_immunization_read` Get Immunization · Read-only Get one Immunization resource from Epic by its FHIR ID. Returns the Immunization resource: vaccineCode, status, occurrence date, lot number, site, route, dose and performer. Use this when you already have the Immunization ID. Use epic_immunization_search to list a patient's immunization history. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `immunization_id` (`string`, required): FHIR logical ID of the Immunization resource to retrieve, as returned in the id field of a Immunization search result or in a reference such as Immunization/. Example: 12345. Example input: `{"immunization_id":""}` ### `epic_immunization_search` Search Immunizations · Read-only Search a patient's immunization history in Epic. Returns a FHIR searchset Bundle whose entry array holds matching Immunization resources (vaccineCode, status, occurrenceDateTime, lotNumber and performer) and a 'next' link when more pages exist. Use this to check what vaccines a patient has had. Use epic_immunization_read for one immunization by ID. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `patient_id` (`string`, required): FHIR ID of the patient whose immunizations to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `_count` (`integer`, optional): Maximum number of results Epic returns in one page of the search Bundle. When more results exist, the Bundle's link array has a 'next' URL. Example: 20. - `date` (`string`, optional): Filter by the vaccination administration date. Use a FHIR date (YYYY-MM-DD) or dateTime, optionally with a prefix such as ge (on or after), le (on or before), gt or lt. Example: ge2024-01-01. - `status` (`string`, optional): Immunization status: completed, entered-in-error or not-done. Leave blank for all. One of: `completed`, `entered-in-error`, `not-done`. Example input: `{"patient_id":""}` ### `epic_location_read` Get Location · Read-only Get one Location resource from Epic by its FHIR ID. Returns the Location resource: name, status, type, address, telecom and managing organization. Use this when you already have the Location ID. Use epic_location_search to find locations by name or address. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `location_id` (`string`, required): FHIR logical ID of the Location resource to retrieve, as returned in the id field of a Location search result or in a reference such as Location/. Example: 12345. Example input: `{"location_id":""}` ### `epic_location_search` Search Locations · Read-only Search locations (departments, clinics, facilities) in the health system's Epic directory. Returns a FHIR searchset Bundle whose entry array holds matching Location resources (name, status, type, address and telecom) and a 'next' link when more pages exist. Use this to find a department or facility. Use epic_location_read for one location by ID. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `_count` (`integer`, optional): Maximum number of results Epic returns in one page of the search Bundle. When more results exist, the Bundle's link array has a 'next' URL. Example: 20. - `address` (`string`, optional): Text in the location's address. Example: Main St. - `address_city` (`string`, optional): City of the location. Example: Madison. - `address_postalcode` (`string`, optional): Postal code of the location. Example: 53703. - `address_state` (`string`, optional): State of the location (two-letter code). Example: WI. - `identifier` (`string`, optional): Location identifier, such as an NPI. Example: 12345. - `name` (`string`, optional): Name of the location. Example: Internal Medicine Clinic. Example input: `{}` ### `epic_medication_read` Get Medication · Read-only Get one Medication resource from Epic by its FHIR ID. Returns the Medication resource: code (RxNorm and others), form, ingredients and strength. Use this when you already have the Medication ID. Medication IDs come from MedicationRequest.medicationReference returned by epic_medication_request_search. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `medication_id` (`string`, required): FHIR logical ID of the Medication resource to retrieve, as returned in the id field of a Medication search result or in a reference such as Medication/. Example: 12345. Example input: `{"medication_id":""}` ### `epic_medication_request_read` Get Medication Order · Read-only Get one MedicationRequest resource from Epic by its FHIR ID. Returns the MedicationRequest resource: medication, status, intent, category, dosage instructions, dispense request, requester and authoredOn. Use this when you already have the MedicationRequest ID. Use epic_medication_request_search to list a patient's medication orders. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `medication_request_id` (`string`, required): FHIR logical ID of the MedicationRequest resource to retrieve, as returned in the id field of a MedicationRequest search result or in a reference such as MedicationRequest/. Example: 12345. Example input: `{"medication_request_id":""}` ### `epic_medication_request_search` Search Medication Orders · Read-only Search a patient's signed medication orders in Epic, optionally filtered by status, category, intent or date. Returns a FHIR searchset Bundle whose entry array holds matching MedicationRequest resources (medicationReference, status, intent, dosageInstruction, requester and authoredOn) and a 'next' link when more pages exist. Use this to review a patient's current or past medications. Use epic_medication_read to resolve a medicationReference. Use epic_medication_request_read for one order by ID. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `patient_id` (`string`, required): FHIR ID of the patient whose medication orders to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `_count` (`integer`, optional): Maximum number of results Epic returns in one page of the search Bundle. When more results exist, the Bundle's link array has a 'next' URL. Example: 20. - `authoredon` (`string`, optional): Filter by the date the prescription was written. Use a FHIR date (YYYY-MM-DD) or dateTime, optionally with a prefix such as ge (on or after), le (on or before), gt or lt. Example: ge2024-01-01. - `category` (`string`, optional): Order category: inpatient, outpatient, community or discharge. Leave blank for all. - `encounter` (`string`, optional): FHIR ID of the Encounter during which the order was created. Example: 12345. - `intent` (`string`, optional): Order intent: order or plan. One of: `order`, `plan`. - `status` (`string`, optional): Order status: active, on-hold, completed or stopped. Leave blank for all. One of: `active`, `on-hold`, `completed`, `stopped`. Example input: `{"patient_id":""}` ### `epic_next_page` Get Next Page of Search Results · Read-only Get the next page of results from an Epic search tool by following the 'next' link in its result Bundle. Returns a FHIR searchset Bundle like the original search; when it has no 'next' link, it is the last page. Use this after any epic_*_search tool when its result has a 'next' link. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `next_page_path` (`string`, required): The part of the search result's 'next' link url that comes after /api/FHIR/R4/, starting with the resource type and keeping the query string; no leading slash. Example: for the next link https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/Observation?sessionID=16-ABC12345 pass Observation?sessionID=16-ABC12345. Example input: `{"next_page_path":""}` ### `epic_observation_read` Get Observation · Read-only Get one Observation resource from Epic by its FHIR ID. Returns the Observation resource: code, category, value (quantity, string or coded), effective time, status, reference range and components. Use this when you already have the Observation ID. Use epic_observation_search to list a patient's labs, vitals or social history. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `observation_id` (`string`, required): FHIR logical ID of the Observation resource to retrieve, as returned in the id field of a Observation search result or in a reference such as Observation/. Example: 12345. Example input: `{"observation_id":""}` ### `epic_observation_search` Search Observations · Read-only Search a patient's observations in Epic (lab results, vital signs, social history and other categories) by category or code. Returns a FHIR searchset Bundle whose entry array holds matching Observation resources (code, value, effectiveDateTime, status, category and interpretation) and a 'next' link when more pages exist. Send exactly one of Category or Code: Epic rejects a search with both or neither. Use epic_diagnostic_report_search for whole lab or imaging reports. Use epic_observation_read for one observation by ID. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `patient_id` (`string`, required): FHIR ID of the patient whose observations to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `_count` (`integer`, optional): Maximum number of results Epic returns in one page of the search Bundle. When more results exist, the Bundle's link array has a 'next' URL. Example: 20. - `category` (`string`, optional): Observation category. Send this or Code, not both. Common values: laboratory, vital-signs, social-history, exam, survey. Example: vital-signs. - `code` (`string`, optional): Observation code as | (a LOINC code when no system is given). Send this or Category, not both. Example: http://loinc.org|8867-4. - `date` (`string`, optional): Filter by when the observation was taken or the specimen was collected. Use a FHIR date (YYYY-MM-DD) or dateTime, optionally with a prefix such as ge (on or after), le (on or before), gt or lt. Example: ge2024-01-01. - `encounter` (`string`, optional): FHIR ID of an Encounter, to return observations from that visit. Example: 12345. - `status` (`string`, optional): Observation status: registered, preliminary, final, amended, corrected, cancelled or entered-in-error. Example input: `{"patient_id":""}` ### `epic_organization_read` Get Organization · Read-only Get one Organization resource from Epic by its FHIR ID. Returns the Organization resource: name, identifiers, type, telecom and address. Use this when you already have the Organization ID. Organization IDs come from references in other resources (for example Patient.managingOrganization or Coverage.payor). Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `organization_id` (`string`, required): FHIR logical ID of the Organization resource to retrieve, as returned in the id field of a Organization search result or in a reference such as Organization/. Example: 12345. Example input: `{"organization_id":""}` ### `epic_patient_match` Match Patient · Read-only Find the single Epic patient record that matches a set of demographics with high confidence ($match). Returns a searchset Bundle with one Patient when Epic finds exactly one certain match; otherwise an OperationOutcome explaining why (multiple, low-confidence or no matches). Use this when the agent must resolve one patient without a human choosing from a list. Use epic_patient_search to list candidates. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `birth_date` (`string`, required): Patient's exact date of birth as YYYY-MM-DD. Required for a high-confidence match. Example: 1980-01-01. - `family` (`string`, required): Patient's exact family (last) name. Required for a high-confidence match. Example: Smith. - `given` (`array`, required): Patient's given names (first, then middle). Example: ["Jane"]. - `address_line` (`string`, optional): Street line of the patient's home address. Improves match confidence. Example: 123 Main St. - `city` (`string`, optional): City of the patient's home address. Example: Madison. - `email` (`string`, optional): Patient's email address. Improves match confidence. Example: patient@example.com. - `gender` (`string`, optional): Administrative gender: male, female, other or unknown. Improves match confidence. One of: `male`, `female`, `other`, `unknown`. - `identifier_system` (`string`, optional): System URI or OID of an identifier to look the patient up by, such as an MRN type OID. Send together with Identifier Value. Example: urn:oid:1.2.3.4. - `identifier_value` (`string`, optional): Value of the identifier named by Identifier System, such as the MRN. Epic still validates the demographics against the record it finds. Example: 12345. - `phone` (`string`, optional): Patient's home phone number. Improves match confidence. Example: 555-555-0100. - `postal_code` (`string`, optional): Postal (ZIP) code of the patient's home address. Example: 53703. - `state` (`string`, optional): State of the patient's home address (two-letter code). Example: WI. Example input: `{"birth_date":"","family":"","given":["Jane"]}` ### `epic_patient_read` Get Patient · Read-only Get one Patient resource from Epic by its FHIR ID. Returns the Patient resource: name, gender, birth date, identifiers such as MRN, telecom, address, language and general practitioner. Use this when you already have the Patient ID. Use epic_patient_search to find a patient by name, birth date or identifier. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `patient_id` (`string`, required): FHIR logical ID of the Patient resource to retrieve, as returned in the id field of a Patient search result or in a reference such as Patient/. Example: 12345. Example input: `{"patient_id":""}` ### `epic_patient_search` Search Patients · Read-only Search Epic patient records by demographics such as name, birth date, gender, identifier (e.g. MRN) or phone. Returns a FHIR searchset Bundle whose entry array holds matching Patient resources (id, name, gender, birthDate, identifier, telecom and address) and a 'next' link when more pages exist. Use this to find candidate patients and let the clinician pick one. Use epic_patient_match when exactly one high-confidence match is required. Use epic_patient_read when you already have the ID. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `_count` (`integer`, optional): Maximum number of results Epic returns in one page of the search Bundle. When more results exist, the Bundle's link array has a 'next' URL. Example: 20. - `address` (`string`, optional): Street address line of the patient's home address. Example: 123 Main St. - `address_city` (`string`, optional): City of the patient's home address. Example: Madison. - `address_postalcode` (`string`, optional): Postal (ZIP) code of the patient's home address. Example: 53703. - `address_state` (`string`, optional): State of the patient's home address, as a two-letter code. Example: WI. - `birthdate` (`string`, optional): Patient's date of birth in YYYY-MM-DD format. Example: 1980-01-01. - `email` (`string`, optional): Patient's email address. Example: patient@example.com. - `family` (`string`, optional): Patient's family (last) name. Partial matches are allowed. Example: Smith. - `gender` (`string`, optional): Administrative gender of the patient: male, female, other or unknown. Ignored by Epic when legal sex is also sent. One of: `male`, `female`, `other`, `unknown`. - `given` (`string`, optional): Patient's given (first or middle) name. Example: Jane. - `identifier` (`string`, optional): A patient identifier such as an MRN, formatted as | or just . Example: MRN|12345. - `name` (`string`, optional): Any part of the patient's name, used when family and given are not provided. Example: Jane Smith. - `phone` (`string`, optional): Patient's phone number. Example: 555-555-0100. - `telecom` (`string`, optional): Patient's phone number or email address. Example: 555-555-0100. Example input: `{}` ### `epic_patient_summary` Get Patient Summary · Read-only Generate an International Patient Summary (IPS) document for one patient ($summary). Returns an IPS document Bundle: a Composition with narrative sections plus the patient's Patient, problem-list Condition, AllergyIntolerance, MedicationRequest, Medication, Immunization and Organization resources. Use this for a one-call chart overview. Use the per-resource search tools (e.g. epic_condition_search) for filtered or paged detail. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `patient_id` (`string`, required): FHIR ID of the patient to summarize. Get it from epic_patient_search or epic_patient_match. Example: 12345. Example input: `{"patient_id":""}` ### `epic_practitioner_read` Get Practitioner · Read-only Get one Practitioner resource from Epic by its FHIR ID. Returns the Practitioner resource: name, identifiers such as NPI, telecom, address, gender and qualifications. Use this when you already have the Practitioner ID. Use epic_practitioner_search to find a practitioner by name or NPI. The signed-in clinician's own ID is in the fhirUser claim. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `practitioner_id` (`string`, required): FHIR logical ID of the Practitioner resource to retrieve, as returned in the id field of a Practitioner search result or in a reference such as Practitioner/. Example: 12345. Example input: `{"practitioner_id":""}` ### `epic_practitioner_role_read` Get Practitioner Role · Read-only Get one PractitionerRole resource from Epic by its FHIR ID. Returns the PractitionerRole resource: practitioner, organization, code (role), specialty, location and telecom. Use this when you already have the PractitionerRole ID. Use epic_practitioner_role_search to find roles by practitioner, location or specialty. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `practitioner_role_id` (`string`, required): FHIR logical ID of the PractitionerRole resource to retrieve, as returned in the id field of a PractitionerRole search result or in a reference such as PractitionerRole/. Example: 12345. Example input: `{"practitioner_role_id":""}` ### `epic_practitioner_role_search` Search Practitioner Roles · Read-only Search practitioner roles in the Epic directory by practitioner, organization, location, specialty or identifier. Returns a FHIR searchset Bundle whose entry array holds matching PractitionerRole resources (practitioner, organization, code, specialty and location) and a 'next' link when more pages exist. Send at least one of Practitioner, Organization, Location, Specialty or Identifier. Use epic_practitioner_search to find people by name. Use epic_practitioner_role_read for one role by ID. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `_count` (`integer`, optional): Maximum number of results Epic returns in one page of the search Bundle. When more results exist, the Bundle's link array has a 'next' URL. Example: 20. - `identifier` (`string`, optional): A practitioner identifier such as an NPI. Example: http://hl7.org/fhir/sid/us-npi|1234567890. - `location` (`string`, optional): FHIR ID of a Location where the practitioner provides care. Example: 12345. - `organization` (`string`, optional): FHIR ID of the Organization the practitioner acts for. Example: 12345. - `practitioner` (`string`, optional): FHIR ID of the Practitioner. Example: 12345. - `specialty` (`string`, optional): Specialty as | using the NUCC system. Example: http://nucc.org/provider-taxonomy|207Q00000X. Example input: `{}` ### `epic_practitioner_search` Search Practitioners · Read-only Search practitioners in the health system's Epic directory by name or identifier such as NPI. Returns a FHIR searchset Bundle whose entry array holds matching Practitioner resources (name, identifier, telecom and address) and a 'next' link when more pages exist. Send at least one of Name, Family or Identifier. Use epic_practitioner_role_search for specialties and locations. Use epic_practitioner_read for one practitioner by ID. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `_count` (`integer`, optional): Maximum number of results Epic returns in one page of the search Bundle. When more results exist, the Bundle's link array has a 'next' URL. Example: 20. - `family` (`string`, optional): Part of the practitioner's family (last) name. Example: Smith. - `given` (`string`, optional): Part of the practitioner's given name. Family is also required with this. Example: Jane. - `identifier` (`string`, optional): A practitioner identifier such as an NPI, as | or |. When set, Epic ignores the other filters. Example: http://hl7.org/fhir/sid/us-npi|1234567890. - `name` (`string`, optional): Free text that matches part of the practitioner's family name, given name or both. Overrides Family and Given. Example: Smith. Example input: `{}` ### `epic_procedure_read` Get Procedure · Read-only Get one Procedure resource from Epic by its FHIR ID. Returns the Procedure resource: code, status, category, performed date or period, performer, reason and encounter. Use this when you already have the Procedure ID. Use epic_procedure_search to list a patient's procedures. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `procedure_id` (`string`, required): FHIR logical ID of the Procedure resource to retrieve, as returned in the id field of a Procedure search result or in a reference such as Procedure/. Example: 12345. Example input: `{"procedure_id":""}` ### `epic_procedure_search` Search Procedures · Read-only Search a patient's procedures in Epic, such as surgeries and completed procedure orders. Returns a FHIR searchset Bundle whose entry array holds matching Procedure resources (code, status, category, performedDateTime or performedPeriod and performer) and a 'next' link when more pages exist. Set Category to 387713003 for surgical history or 103693007 for diagnostic procedure orders. Use epic_procedure_read for one procedure by ID. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `patient_id` (`string`, required): FHIR ID of the patient whose procedures to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `_count` (`integer`, optional): Maximum number of results Epic returns in one page of the search Bundle. When more results exist, the Bundle's link array has a 'next' URL. Example: 20. - `category` (`string`, optional): Procedure category as a SNOMED CT code: 387713003 (surgical procedure) or 103693007 (diagnostic procedure orders). Example: 387713003. - `code` (`string`, optional): Procedure code (e.g. CPT or SNOMED) as | or . Example: http://www.ama-assn.org/go/cpt|45378. - `date` (`string`, optional): Filter by the date or period the procedure was performed. Use a FHIR date (YYYY-MM-DD) or dateTime, optionally with a prefix such as ge (on or after), le (on or before), gt or lt. Example: ge2024-01-01. - `encounter` (`string`, optional): FHIR ID of the Encounter the procedure belongs to. Example: 12345. - `status` (`string`, optional): Procedure status, such as completed, in-progress, not-done or entered-in-error. Example input: `{"patient_id":""}` ### `epic_schedule_get` Get Schedule · Read-only Get one Schedule from Epic by its FHIR ID (STU3). Returns the Schedule resource, whose actor array references the Practitioner and Location (department) the schedule belongs to, with display names. Use this to find which provider and department a slot from epic_appointment_find_slots or epic_slot_get is for. Requires a Schedule ID from a slot's schedule reference. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `schedule_id` (`string`, required): FHIR ID of the Schedule: the part after Schedule/ in a Slot's schedule.reference (from epic_slot_get or a contained Slot in epic_appointment_find_slots). Example: 12345. Example input: `{"schedule_id":""}` ### `epic_service_request_read` Get Order · Read-only Get one ServiceRequest resource from Epic by its FHIR ID. Returns the ServiceRequest resource: code, category, status, intent, priority, requester, reason, occurrence and specimen. Use this when you already have the ServiceRequest ID. Use epic_service_request_search to list a patient's orders and referrals. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `service_request_id` (`string`, required): FHIR logical ID of the ServiceRequest resource to retrieve, as returned in the id field of a ServiceRequest search result or in a reference such as ServiceRequest/. Example: 12345. Example input: `{"service_request_id":""}` ### `epic_service_request_search` Search Orders · Read-only Search a patient's procedure, lab, imaging and referral orders in Epic. Returns a FHIR searchset Bundle whose entry array holds matching ServiceRequest resources (code, category, status, intent, priority, requester and authoredOn) and a 'next' link when more pages exist. Use this to see what has been ordered. Use epic_diagnostic_report_search for the results. Use epic_service_request_read for one order by ID. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. If the result has a 'next' link, use epic_next_page to get more. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `patient_id` (`string`, required): FHIR ID of the patient whose orders to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `_count` (`integer`, optional): Maximum number of results Epic returns in one page of the search Bundle. When more results exist, the Bundle's link array has a 'next' URL. Example: 20. - `authored` (`string`, optional): Filter by when the order was signed. Use a FHIR date (YYYY-MM-DD) or dateTime, optionally with a prefix such as ge (on or after), le (on or before), gt or lt. Example: ge2024-01-01. - `category` (`string`, optional): Order category as |. Epic order-type systems are organization-specific OIDs; US Core ServiceRequest category codes (e.g. http://snomed.info/sct|108252007 laboratory) also work. Example: http://snomed.info/sct|108252007. - `code` (`string`, optional): Procedure code mapped to the order (CPT, SNOMED or LOINC) as | or . Example: http://loinc.org|24323-8. - `encounter` (`string`, optional): FHIR ID of the Encounter the order belongs to. Example: 12345. - `status` (`string`, optional): Order status: draft, active, completed, revoked or unknown. Leave blank for all. One of: `draft`, `active`, `completed`, `revoked`, `unknown`. Example input: `{"patient_id":""}` ### `epic_slot_get` Get Slot · Read-only Get one appointment Slot from Epic by its FHIR ID (STU3). Returns the Slot resource: start and end time and a schedule reference that leads to the provider and department; status (busy-tentative) is included only for slots returned by epic_appointment_find_slots. Use this to look up a slot held by a proposed appointment. Use epic_schedule_get to see whose schedule the slot belongs to. Requires a Slot ID from epic_appointment_find_slots: Epic serves Slot only for slots surfaced there. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `slot_id` (`string`, required): FHIR ID of the Slot, taken from the id of the contained Slot in an epic_appointment_find_slots result (the appointment's slot reference is #; pass the id without the #). Example: 12345. Example input: `{"slot_id":""}` ### `epic_allergy_intolerance_create` Create Allergy · Write File a new allergy or intolerance for a patient in Epic. Returns the created AllergyIntolerance resource. Epic saves it to a holding area with verification status 'unconfirmed' until a clinician reconciles it into the chart. Use this to record an allergy the patient reports. Use epic_allergy_intolerance_search first to avoid filing a duplicate. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `patient_id` (`string`, required): FHIR ID of the patient whose allergy to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `substance_text` (`string`, required): Name of the allergen as free text. Example: Penicillin. - `category` (`string`, optional): Category of the allergen: food, medication, environment or biologic. One of: `food`, `medication`, `environment`, `biologic`. - `clinical_status` (`string`, optional): Clinical status of the allergy: active or resolved. A resolved allergy needs an onset end date in the past. One of: `active`, `resolved`. - `criticality` (`string`, optional): Risk of clinical harm: low, high or unable-to-assess. One of: `low`, `high`, `unable-to-assess`. - `note` (`string`, optional): Free-text comment about the allergy. Example: Reported by patient at intake. - `onset_date` (`string`, optional): Date the allergy was identified, as YYYY-MM-DD. Example: 2024-01-15. - `reaction` (`string`, optional): Reaction the patient had, as free text. Example: Hives. - `reaction_severity` (`string`, optional): Severity of the reaction: mild, moderate or severe. Used only when Reaction is set. One of: `mild`, `moderate`, `severe`. - `substance_code` (`string`, optional): Code for the allergen in the system given by Substance System, such as an RxNorm code. Example: 7980. - `substance_system` (`string`, optional): Coding system URI or OID of Substance Code. Example: http://www.nlm.nih.gov/research/umls/rxnorm. - `type` (`string`, optional): Underlying mechanism: allergy or intolerance. One of: `allergy`, `intolerance`. Example input: `{"patient_id":"","substance_text":""}` ### `epic_appointment_book` Book Appointment · Write Book, for a patient, one of the proposed appointments that epic_appointment_find_slots returned ($book, STU3). Returns the booked Appointment: status booked, start, end, minutesDuration, serviceType (visit type), the appointment CSN in identifier, and participants for the patient, provider and department. Use this only after the clinician and patient choose one proposed time. Use epic_appointment_find_slots to get the options. Use epic_appointment_search or epic_appointment_read for appointments that already exist. Requires the patient's FHIR ID and a proposed Appointment ID from epic_appointment_find_slots, run shortly before: Epic holds proposed slots only briefly. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `appointment_id` (`string`, required): ID of the proposed Appointment to book: the id of one entry returned by epic_appointment_find_slots. These IDs work only with this tool, not with epic_appointment_read. Example: 12345. - `patient_id` (`string`, required): FHIR ID of the patient to book for. Epic's R4 and STU3 APIs share patient FHIR IDs, so the id from epic_patient_search, epic_patient_match or epic_patient_create works. Example: 12345. - `appointment_note` (`string`, optional): Optional free-text note to store with the appointment. Epic keeps appointment notes up to 500 characters. Example: Follow-up for knee pain. Example input: `{"appointment_id":"","patient_id":""}` ### `epic_condition_create` Create Problem · Write Add a problem list item for a patient in Epic. Returns the created Condition resource. Epic saves it to a holding area with verification status 'provisional' until a clinician reconciles it into the problem list. Use this to propose a new problem. Use epic_condition_search with category problem-list-item first to avoid duplicates. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `code` (`string`, required): Diagnosis code for the problem in the system given by Code System. ICD-10 and SNOMED CT are preferred. Example: E11.9. - `display` (`string`, required): Human-readable name of the problem. Example: Type 2 diabetes mellitus without complications. - `onset_date` (`string`, required): Date or estimated date the problem began, as YYYY-MM-DD. Example: 2024-01-15. - `patient_id` (`string`, required): FHIR ID of the patient whose problem to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `abatement_date` (`string`, optional): Date the problem resolved, as YYYY-MM-DD. Set Clinical Status to resolved when this is in the past. Example: 2024-06-01. - `clinical_status` (`string`, optional): Clinical status: active or resolved. Must be resolved when Abatement Date is in the past. One of: `active`, `resolved`. - `code_system` (`string`, optional): Coding system of Code. Use http://hl7.org/fhir/sid/icd-10-cm for ICD-10-CM or http://snomed.info/sct for SNOMED CT. - `note` (`string`, optional): Free-text comment, up to 450 characters. Example: Diet controlled. Example input: `{"code":"","display":"","onset_date":"","patient_id":""}` ### `epic_document_reference_create` Create Clinical Note · Write File a plain-text clinical note to a patient's encounter in Epic. Returns the created DocumentReference resource for the note. Use this to write a note such as a progress note. Use docStatus preliminary to leave it for a clinician to sign; final files it as signed. Requires a patient FHIR ID and an encounter ID that can hold a note: run epic_patient_search and epic_encounter_search first. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `encounter_id` (`string`, required): FHIR ID of the clinical encounter to file the note to. It must belong to the patient. Example: 12345. - `note_text` (`string`, required): Plain text of the note. The tool base64-encodes it for Epic; do not send HTML or RTF. Example: Patient seen for follow-up. Vitals stable. - `patient_id` (`string`, required): FHIR ID of the patient whose note to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `type_code` (`string`, required): LOINC code (or Epic note category ID) for the note type. Example: 11506-3 (progress note). - `date` (`string`, optional): Date and time of the note, ISO 8601. Example: 2024-01-15T14:30:00Z. - `doc_status` (`string`, optional): Status to file the note with: preliminary (incomplete, for a clinician to finish and sign) or final (signed). One of: `preliminary`, `final`. - `type_system` (`string`, optional): Coding system of Type Code. Defaults to http://loinc.org; use the organization's note-category OID for an Epic note category ID. Example input: `{"encounter_id":"","note_text":"","patient_id":"","type_code":""}` ### `epic_observation_create` Create Vital Sign · Write File one vital sign or flowsheet reading for a patient's open encounter in Epic. Returns the created Observation resource (category vital-signs, status final). Use this to document a single measurement such as temperature, pulse or weight. Epic rejects a reading that already exists at the same time, on a closed encounter or on a future appointment. Requires a patient FHIR ID and an open encounter ID: run epic_patient_search and epic_encounter_search first. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `code` (`string`, required): Code of the measurement: a LOINC code (e.g. 8310-5 body temperature, 8867-4 heart rate, 29463-7 body weight) or an Epic flowsheet row ID. LOINC works only when it maps to a single flowsheet row; if Epic answers "Multiple Flowsheet rows found by given codes", send the flowsheet row ID instead (e.g. 8 for pulse) with the organization's flowsheet-row OID in Code System. Example: 8310-5. - `effective_date_time` (`string`, required): Date and time the reading was taken, ISO 8601 with a time zone. Example: 2024-01-15T14:30:00Z. - `encounter_id` (`string`, required): FHIR ID of the open encounter to file the reading to. Required for clinician apps. Example: 12345. - `patient_id` (`string`, required): FHIR ID of the patient whose reading to return. Get it from epic_patient_search or epic_patient_match. Example: 12345. - `code_system` (`string`, optional): Coding system of Code. Defaults to http://loinc.org, which works when the LOINC code maps to one flowsheet row. If Epic answers "Multiple Flowsheet rows found by given codes", send the flowsheet row ID as Code with the organization's flowsheet-row OID system: urn:oid:1.2.840.114350.1.13.0.1.7.2.707679 in Epic's sandbox; in production, the organization's own OID ending .7.2.707679. Example: urn:oid:1.2.840.114350.1.13.0.1.7.2.707679. - `note` (`string`, optional): Comment on the reading, up to 254 characters. Example: Taken after exercise. - `unit` (`string`, optional): Unit for Value Quantity in UCUM form. Epic validates and converts height, weight and temperature units. Example: Cel. - `value_quantity` (`number`, optional): Numeric value of the reading. Send this or Value String. Example: 37.2. - `value_string` (`string`, optional): Text value for a reading without units. Send this or Value Quantity. Example: Regular. Example input: `{"code":"","effective_date_time":"","encounter_id":"","patient_id":""}` ### `epic_patient_create` Create Patient · Write Register a patient in Epic from demographics, or get back the existing record when Epic matches one. Returns the created or matched Patient resource (Prefer: return=representation), including its new FHIR id. Use this only after epic_patient_search or epic_patient_match finds no existing record; Epic returns an existing patient when the identifier or demographics match with high confidence. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `family_name` (`string`, required): Patient's family (last) name. Example: Testpatient. - `given_names` (`array`, required): Patient's given names: first name, then an optional middle name. Epic files at most two. Example: ["Jane"]. - `identifier_system` (`string`, required): System OID or URI of the patient identifier to file. Epic requires an identifier on create and rejects a patient without one (400 "A required element is missing."). Use the SSN OID urn:oid:2.16.840.1.113883.4.1 or the organization's MRN system. Epic also uses it to look for an existing patient. Example: urn:oid:2.16.840.1.113883.4.1. - `identifier_value` (`string`, required): Value of the identifier named by Identifier System, such as the SSN or MRN. Epic requires an identifier on create. Example: 123-45-6789. - `address_line` (`string`, optional): Street line of the home address. Epic files only the home address and needs a street line and city when an address is sent. Example: 123 Main St. - `birth_date` (`string`, optional): Date of birth as YYYY-MM-DD. Example: 1980-01-01. - `city` (`string`, optional): City of the home address. Example: Madison. - `country` (`string`, optional): Country of the home address. Example: USA. - `email` (`string`, optional): Email address. Example: patient@example.com. - `gender` (`string`, optional): Patient's legal sex as a FHIR administrative gender: male, female, other or unknown. One of: `male`, `female`, `other`, `unknown`. - `phone` (`string`, optional): Home phone number. Example: 555-555-0100. - `postal_code` (`string`, optional): ZIP code of the home address (nnnnn or nnnnn-nnnn). Example: 53703. - `state` (`string`, optional): State of the home address as a two-letter postal code. Example: WI. Example input: `{"family_name":"","given_names":["Jane"],"identifier_system":"","identifier_value":""}` ## Related Other Healthcare & life sciences connectors ([all 16](/agentkit/connectors/?category=healthcare)): - [Synapse MCP server](/agentkit/connectors/synapsemcp/): Vendor MCP, OAuth, 48 tools - [Availity](/agentkit/connectors/availity/): Scalekit connector, Service account, 11 tools - [Healthie](/agentkit/connectors/healthie/): Scalekit connector, API key, 44 tools --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |