Epic on FHIR Integration

Overview

Epic on FHIR is the VINSI.AI healthcare integration for Epic electronic health record environments. The integration uses Epic FHIR APIs to support patient lookup, appointment lookup, slot search, and appointment booking from AI phone agent workflows.

Unlike HubSpot or Salesforce, each organization does not create its own OAuth app. VINSI.AI provides the Epic client ID and signing keys, and the health system's Epic team activates that client in their Epic environment.

Activation

Epic access must be enabled by the health system before the connection can be verified. Their Epic or Interconnect team should activate the VINSI.AI Epic on FHIR backend client and enable the required FHIR resources.

• Authentication: OAuth 2.0 Backend Services with RS384-signed JWT client assertions
• Public keys: /api/epic/jwks
• FHIR versions: R4 for patients and appointment lookup; STU3 for Epic scheduling operations

Client Registration

The health system's Epic team activates VINSI.AI using the registration below. Everything on this page corresponds to the VINSI.AI app entry on fhir.epic.com (audience: Backend Systems, use case: General).

Application Name        VINSI AI Scheduling Assistant
Application Audience    Backend Systems
Use Case                General
Public Documentation    https://docs.vinsi.ai/api-integration/epic

Production Client ID        dfad258d-8069-42bc-a500-b094d9d9bfa4
Non-Production Client ID    49d193bd-cb41-4856-b811-c246ce7d0f6c

JWK Set URL (non-prod)      https://dashboard.vinsi.ai/api/epic/jwks
JWK Set URL (production)    https://dashboard.vinsi.ai/api/epic/jwks-prod

Signing algorithm       RS384
Key rotation            Distinct sandbox / production key pairs; rotated
                        under change control with dual-key overlap so
                        activated systems are never left offline.

Requested FHIR resources

These are the exact FHIR resources on the app registration. VINSI.AI does not request write scopes other than the two STU3 scheduling operations.

Reads
  Patient.Read (R4)
  Patient.Search (R4)
  Appointment.Read / Appointment.Search (R4)
  Slot.Read (STU3)

Scheduling operations
  Appointment.$find (STU3)
  Appointment.$book (STU3)

No chart writes, no demographic updates, no order entry, no document uploads. VINSI.AI holds no other Epic scopes.

Data Handling & Security

All Epic data is treated as PHI. This section is the primary reference for a health-system security review.

What VINSI.AI reads from Epic

• Patient demographics returned by Patient.Search (name, DOB, phone, MRN, internal FHIR id) — used only to identify the caller and hand the id to downstream tools.
• Upcoming appointments returned by Appointment.Search — used to prevent duplicate booking.
• Slots returned by $find — read only to offer times to the caller.

What VINSI.AI writes to Epic

• One $book call per confirmed appointment, with an optional caller-provided visit note. No other writes.

Data flow

Caller (phone)
   │
   ▼
Telephony (SIP)  ──►  VINSI.AI worker
   │                   │
   │                   ▼
   │           VINSI.AI language model (BAA-covered; no
   │           model-training on health-system data)
   │                   │
   │                   ▼
   │           Epic on FHIR tool calls (JWT-signed,
   │           per-health-system endpoint)
   │                   │
   ▼                   ▼
Voice back      Epic response
to caller       (patient, appointments, slots, $book confirmation)

Storage & retention

• Tool-call log (request, response, patient id, timestamp, agent id, call id) — encrypted at rest, retained per the health system's configured retention policy.
• Call recording & transcript — encrypted at rest and in transit, retention configurable per organization.
• No LLM training on health-system data. Prompts and tool results are not used to train or fine-tune any model.
• Encryption in transit: TLS 1.2+ for every external hop (Epic, LLM provider, telephony, storage).

Compliance posture

• HIPAA: VINSI.AI signs a Business Associate Agreement (BAA) with the health system prior to enabling any production Epic environment. Sub-processors (LLM provider, storage, telephony) are BAA-covered.
• SOC 2 & HITRUST: A formal SOC 2 Type II engagement and HITRUST CSF certification are on the VINSI.AI security roadmap. Current documentation and pen-test summaries are available under NDA on request.
• Access controls: Production access is role-based, MFA-required, and audit-logged. Signing keys are held in restricted secrets storage.
• Incident response: Suspected security incidents are triaged within one business hour and communicated to the health-system contact per the BAA terms.

Connection Settings

After the health system shares its Epic endpoint information, configure the connection in VINSI.AI.

1. Navigate to Settings -> API Integration -> Epic
2. Enter an Environment Name, such as the health system name and whether it is test or production
3. Enter the FHIR R4 Base URL
4. Enter the FHIR STU3 Base URL used for appointment search and booking
5. Enter the OAuth Token URL
6. Enable Production Epic environment only for the health system's live environment
7. Click Save & Verify

If Epic has not activated the VINSI.AI client ID yet, the connection can be saved but may show as awaiting activation until verification succeeds.

Agent Tool Actions

Once Epic is connected, create a tool with the Epic FHIR API tool type. The available resources are Patients and Appointments.

Patients
- Look up Patient
  Endpoint: POST /api/epic/patient-lookup
  Required: family, birthdate
  Optional: given, phone

Appointments
- Get Patient Appointments
  Endpoint: POST /api/epic/get-appointments
  Required: patientId
  Optional: fromDate

- Find Available Appointment Slots
  Endpoint: POST /api/epic/find-slots
  Required: startTime, endTime
  Optional defaults: serviceTypeCode, serviceTypeSystem

- Book Appointment
  Endpoint: POST /api/epic/book-appointment
  Required: patientId, appointmentId
  Optional: note

Patient IDs and appointment IDs should come from previous tool results. The agent should not ask callers to provide these internal Epic identifiers.

Example Scheduling Flow

1. Ask the caller for last name and date of birth, then confirm the spelling and date before searching.
2. Use Look up Patient to find the patient record.
3. Use Get Patient Appointments to review upcoming appointments when needed.
4. Use Find Available Appointment Slots with a short date/time window and the configured service type values.
5. Read the available options to the caller and confirm their selected time.
6. Use Book Appointment with the selected appointment ID and an optional visit note.

Important Notes

• Epic activation is controlled by the health system's Epic team. VINSI.AI cannot verify the connection until that activation is complete.
• Scheduling availability depends on the health system's Cadence configuration, departments, providers, visit types, and service type codes.
• Keep appointment slot search windows short so the agent returns a manageable list of options to the caller.
• Treat Epic responses as PHI. Only configure Epic tools for agents and workflows that are authorized to access patient information.

Support & Governance

How VINSI.AI stays accountable to a health system after go-live.

Contacts

• Support: support@vinsi.ai
• Security & incident response: security@vinsi.ai
• Epic activation questions: epic@vinsi.ai

Change management

• Cadence build changes affecting the pilot (visit types, service type codes, provider filters, decision-tree updates) are handled via a change-notification agreement — the health system notifies VINSI.AI in advance, VINSI.AI validates in sandbox, both parties sign off before promotion.
• Changes to the VINSI.AI agent prompt, escalation logic, or tool schema for a production organization require written approval from a named health-system owner.
• Base LLM model changes are announced in advance and a regression suite is run against representative scenarios before promotion.

Ownership split

• Health system owns: Cadence build, decision trees, provider preferences, escalation targets, HIPAA/BAA compliance obligations, sign-off on production changes.
• VINSI.AI owns: LLM behavior and prompt, Epic tool schema, uptime and monitoring, tool-call auditing, signing-key management, sandbox parity.