Skip to main content

FHIR & HL7 Interoperability

QuickstartAPI ReferenceAuth GuideWebhooksFHIR & HL7SAML / SCIM SSOOpenAPI & SwaggerAPI VersioningAsyncAPI ContractSDK PackagingEvent SchemasRecipesTroubleshooting

FHIR / HL7 Interoperability

Last updated: 2026-02-18

This document describes the implemented FHIR integration surface and healthcare interoperability constraints.

1. Standard and scope

  • FHIR version: R4 (4.0.1)
  • Content type: application/fhir+json
  • Capability statement endpoint: GET /api/fhir/metadata

Supported resources:

  • Patient
  • CarePlan
  • Observation
  • DiagnosticReport
  • MedicationRequest

2. Authentication and authorization

FHIR routes support:

  • Clerk session auth for eligible employer roles, or
  • API key auth with:
    • fhir:read for reads/search
    • fhir:write for creates/updates

Routes are employer-scoped and tenant-isolated.

3. Endpoints

  • GET /api/fhir/metadata
  • GET /api/fhir/Patient
  • POST /api/fhir/Patient
  • GET /api/fhir/Patient/{id}
  • GET /api/fhir/CarePlan
  • GET /api/fhir/Observation
  • GET /api/fhir/DiagnosticReport
  • GET /api/fhir/MedicationRequest
  • POST /api/fhir/smart/launch
  • GET|POST /api/fhir/$export
  • GET /api/fhir/Group/{id}/$export
  • GET /api/fhir/bulk-export/{exportId}
  • GET /api/fhir/bulk-export/{exportId}/download
  • GET /.well-known/smart-configuration
  • GET /api/cds-services
  • POST /api/cds-services/patient-view

4. Search parameters

Patient

  • _id: internal patient user id
  • email: patient email
  • _count: page size (bounded server-side)

CarePlan

  • patient=Patient/{id}
  • _count

Observation

  • patient=Patient/{id}
  • code (matches test name text)
  • _count

DiagnosticReport

  • patient=Patient/{id}
  • _count

MedicationRequest

  • patient=Patient/{id}
  • _count

5. Resource mapping summary

Patient mapping

  • Local User (role=PATIENT) maps to FHIR Patient
  • Primary identifier is local user id
  • Telecom email is required for create mapping

CarePlan mapping

  • Tapering logs map to FHIR CarePlan
  • Current medication and dosage change history map into plan narrative metadata

Observation mapping

  • LabReport.testResults rows map to FHIR Observation
  • Numeric results map to valueQuantity
  • Non-numeric results map to valueString
  • Lab flags map to interpretation codes when provided

DiagnosticReport mapping

  • Each LabReport maps to one DiagnosticReport
  • Associated Observation resources are exposed via result references
  • Abnormal and critical findings map to conclusion

MedicationRequest mapping

  • Current patient medication profile maps to MedicationRequest
  • Current dosage maps to dosageInstruction

6. Error model

FHIR route validation errors return OperationOutcome.

Examples:

  • 400 invalid for wrong resource type
  • 404 not-found for missing patient resource
  • 409 duplicate when creating patient with existing employer-scoped email
  • 422 invalid for payload mapping/validation failures

OperationOutcome responses are also written to audit telemetry (fhir.operation_outcome) for spike monitoring and incident alerting.

7. Example request

Search observations for one patient:

bash
curl "https://<host>/api/fhir/Observation?patient=Patient/<patient_id>&_count=25" \
  -H "x-api-key: mt_live_***" \
  -H "accept: application/fhir+json"

8. HL7 integration note

Current implementation is FHIR-first. Teams needing legacy HL7 v2 exchange should implement a translation layer outside Bounded Health (for example, an interface engine translating v2 messages to FHIR REST calls).

9. Remaining limitations

  • Current SMART launch implementation uses platform-signed bearer tokens and does not expose a full OAuth authorization code flow.
  • CDS Hooks currently includes patient-view only; additional hooks can be added as required.
  • Bulk FHIR export currently emits Patient NDJSON; additional resource types can be added incrementally.
  • US Core validation runs in CI using fixture validation plus optional HL7 validator execution.

10. Production checklist

  • Validate resources with R4 validators in CI before import (npm run fhir:validate-us-core)
  • Treat local IDs as authoritative keys for follow-up reads
  • Implement retry handling for 5xx and network failures
  • Track and alert on OperationOutcome error spikes
    • Automated hourly alerting route: GET /api/cron/integration-alerts