Developer API

MLS FHIR R4 API

Standards-based access to your practice's notes, patients, and visits, plus a separate outbound read-only SMART on FHIR connection.

Base URL
https://scrivara-backend.onrender.com/fhir
Auth — send your API key as a bearer token. Generate one in MLS → Settings → API.
Authorization: Bearer mls_xxxxxxxxxxxxxxxx
Accept: application/fhir+json
Conformance: /fhir/metadata
API-key scopes

Each key carries explicit scopes. New keys default to schedule.read; pass { "scopes": [...] } to POST /api/fhir/keys to choose others. Keys created before scope enforcement keep full access. A signed-in clinician session is never scope-restricted.

schedule.read    read Patient / Encounter / Appointment
schedule.write   create + update Appointment
notes.read       read DocumentReference
notes.write      create DocumentReference
task.read        read Task
task.write       update Task
A request outside the key's scopes returns 403 with a FHIR OperationOutcome.

Patients

GET/fhir/Patient?name=smith

Returns a FHIR Bundle of Patient resources for your practice.

GET/fhir/Patient/{id}

Encounters

GET/fhir/Encounter

Your scheduled/seen visits as FHIR Encounter resources.

Scheduling (Appointment)

GET/fhir/Appointment?patient={id}&date=ge2026-07-01&date=le2026-07-31
GET/fhir/Appointment?_lastUpdated=gt2026-07-01T00:00:00Z
POST/fhir/Appointment
PUT/fhir/Appointment/{id}

Receptionist systems can read, create, reschedule, check in, complete, cancel, or mark a no-show using standard FHIR R4 Appointment status values.

Search + paging — date=ge…/date=le… filter on the appointment date; _lastUpdated=gt<instant> returns rows changed since your last sync, ordered oldest-change-first with a deterministic cursor; _count (default 100, max 500) and _offset page through results via the Bundle's self/next links.

Demographics — an appointment booked online (no linked chart yet) carries a contained Patient resource (name, phone/email, birth date) referenced from its participant. Every appointment has an identifier with system urn:mls:appointment-id (plus urn:mls:external-appointment-id when present) and a meta.tag with system urn:mls:appointment-source (online, staff, fhir-api, …).

Idempotent create — include an identifier with your own system + value on POST /fhir/Appointment. Retries with the same identifier return 200 with the existing appointment instead of creating a duplicate (a fresh create returns 201).

Patient requests (Task)

GET/fhir/Task
PUT/fhir/Task/{id}

Refill, injection-timing, appointment, pain, and office-message requests appear as FHIR Tasks. Update a Task to completed after staff handles it.

Clinical notes (DocumentReference)

GET/fhir/DocumentReference?patient={id}&_since=2026-01-01

The scribe's finished notes. The note text is base64 in content[0].attachment.data.

GET/fhir/DocumentReference/{id}
POST/fhir/DocumentReference

Write a note into MLS:

POST https://scrivara-backend.onrender.com/fhir/DocumentReference
Authorization: Bearer mls_...
Content-Type: application/fhir+json

{
  "resourceType": "DocumentReference",
  "status": "current",
  "subject": { "reference": "Patient/EXTERNAL_ID" },
  "content": [{ "attachment": {
    "contentType": "text/plain",
    "data": "<base64 of the note text>"
  }}]
}

Real-time push (webhooks)

Register a public https endpoint and MLS will POST { "event": "...", "resource": { ... } } for the resource type you subscribe to, HMAC-SHA256-signed in X-MLS-Signature (sha256=<hex> over the raw body with your webhook secret). Failed deliveries are retried once.

POST/api/fhir/webhooks { "url": "https://your-app/webhook", "criteria": "Appointment" }

criteria is DocumentReference (default) or Appointment. Appointment events: appointment.created (online booking, front desk, or API create), appointment.updated (front desk or API update), appointment.confirmed / appointment.cancelled (patient self-service), appointment.deleted (front desk removal). GET /api/fhir/webhooks lists your hooks with last_delivery_at and last_status.

Outbound SMART on FHIR — read-only EMR connection

OAuth tokens are encrypted at rest. Automated write-back is disabled until MLS stores and verifies an authoritative visit-to-EMR-encounter binding.

GET/smart/connect → returns the EMR authorize URL (OAuth2 + PKCE)
GET/smart/callback → EMR redirects here; tokens are stored encrypted
POST/smart/push/{noteId} → fails closed until verified encounter binding is implemented

Status: /smart/status

FHIR® is a registered trademark of HL7. MLS is not affiliated with HL7, athenahealth, Epic, or Oracle Health.