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)

Examples (illustrative)

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

appointment.create (MarIA request to your HIS)

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

Expected response:

{ "appointmentId": 12345, "status": "CONFIRMED" }

appointment.getSlots

{
  "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.