> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# EHR/HIS Integration

> How to connect your EHR/HIS to MarIA for appointment management, directories, and patient authentication

This guide explains how to connect your EHR/HIS to MarIA so the agent can query benefits and slots, and create or cancel appointments in real time during inbound patient calls or WhatsApp conversations. MarIA's webhooks to your HIS are signed with `webhookHmac`.

## For whom

* Hospital/insurer integrators (interoperability team)
* Product teams defining the appointment flow

## Main flows

### 1) Get benefits/services (catalog of reasons/consultations)

* Route: `webhooks > appointment.getBenefits`
* Input: `collectiveId` (insurance ID for filtering if needed), `centerId`, `serviceId`
* Usage: prepares the catalog to calculate available slots.

### 2) Get available slots

* Route: `webhooks > appointment.getSlots`
* Input: `benefitId`, `centerId`, `serviceId`, `collectiveId`, `fromDateEpoch`, …
* Usage: present options to patients during the conversation.

### 3) Create appointment

* Route: `webhooks > appointment.create`
* Input: `slot`, `patientId`, `benefitId`
* Output: `appointmentId`, `status`

### 4) Cancel appointment

* Route: `webhooks > appointment.cancel`
* Input: `appointmentId`, `reason`

### 5) Mark appointment as pending reschedule (WIP)

* Route: `webhooks > appointment.reschedulePending`

### 6) List a patient's appointments

* Route: `webhooks > appointment.getList`

### 7) Directories

* `directory.centers` and `directory.professionals`

### 8) Patient authentication/onboarding

* `patient.authenticate` and `patient.onboard`

## Sequence: appointment request and creation (inbound call)

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor User as Patient (inbound call)
    participant MarIA as MarIA
    participant HIS as EHR/HIS

    User->>MarIA: "I'd like to book an appointment"
    MarIA-->>User: "What center/service do you need?"
    User-->>MarIA: Center and/or service
    MarIA->>HIS: webhook appointment.getBenefits (with user context)
    HIS-->>MarIA: List of available benefits
    MarIA->>HIS: webhook appointment.getSlots (benefitId, centerId, serviceId,...)
    HIS-->>MarIA: Available slots
    MarIA-->>User: Proposes dates/times (options)
    User-->>MarIA: Selects specific date/time
    MarIA->>HIS: webhook appointment.create (slot, patientId, benefitId)
    HIS-->>MarIA: appointmentId / status
    MarIA-->>User: Appointment confirmed by phone
```

## Examples (illustrative)

<Info>
  These routes are webhooks that MarIA invokes towards your HIS. Shown only to illustrate expected payloads.
</Info>

### appointment.create (MarIA request to your HIS)

```json theme={null}
{
  "slot": {"start": "2025-09-01T09:00:00Z", "centerId": "H1", "serviceId": 12},
  "patientId": 4567,
  "benefitId": 789
}
```

Expected response:

```json theme={null}
{ "appointmentId": 12345, "status": "CONFIRMED" }
```

### appointment.getSlots

```json theme={null}
{
  "benefitId": 789,
  "centerId": "H1",
  "serviceId": 12,
  "collectiveId": 55,
  "fromDateEpoch": 1754006400000
}
```

## Integration recommendations

* Always respond with `200` and a valid body; use 4xx for validations.
* Traceability: include `appointmentId` and `patientId` in logs.
* Idempotency for `appointment.create` using a `requestId` if applicable.
* Timezones: use UTC and ISO 8601 formats.

## Production checklist

* [ ] Pre-production environment with anonymized data.
* [ ] Latency and error rate monitoring per endpoint.
* [ ] PII retention/masking in logs.