FHIR R4

The FHIR adapter maps FHIR R4 resources to the same normalized events as HL7 v2, following the HL7 V2-to-FHIR concept maps where they apply, so HL7 and FHIR sites get the same behaviour. Raw resources are never stored.

Endpoints

Accept: application/fhir+json returns a batch-response Bundle with an OperationOutcome per entry; Accept: application/json returns the normalized results. A transient failure returns 503 with Retry-After for the whole request; entries already committed return duplicate on retry.

printf '%s' '{"entry":[],"meta":{"tag":[{"code":"HTEST","system":"http://terminology.hl7.org/CodeSystem/v3-ActReason"}]},"resourceType":"Bundle","type":"batch"}' > body.jsoncurl -sS -X POST 'https://api.sandbox.edflow.space/v1/fhir' \  -H 'Content-Type: application/fhir+json' \  -H "Authorization: Bearer $EDFLOW_ACCESS_TOKEN" \  --data-binary @body.json

Subscription rest-hooks

Backport rest-hook channels send static headers, so a 5-minute token doesn't fit. Use a static API key scoped to fhir:write only in Subscription.channel.header. In customer test and live it needs an IP allowlist and expires within 90 days; update the Subscription before it expires.

Sandbox test marker

In the sandbox, Bundles must carry the HTEST tag (http://terminology.hl7.org/CodeSystem/v3-ActReason#HTEST) in meta.tag; in live it's refused.

Resource mapping

Event ids are {sourceId}:fhir:{resourceType}/{id}/_history/{versionId or meta.lastUpdated}:{n}; recordedAt comes from meta.lastUpdated.

Vendor notes

Epic. The ED treatment team comes back as Encounter.participant, not CareTeam. Encounter search is scoped per patient in the public catalogue, and a general FHIR Subscription API isn't published, so most Epic sites send HL7 v2 (Bridges) for the real-time feed and use FHIR for enrichment or a SMART launch. Backend services use client_credentials with a private_key_jwt assertion signed with RS384 or ES384.

Oracle Health Millennium. CareTeam supports encounter-level teams with roles and periods, which fits the ED well. R4 Subscriptions aren't in the public documentation, so real-time events usually come from HL7 v2 outbound through Oracle's interface tooling.

Any vendor. A FHIR relay or subscription product in front of the EHR works with $ingest.

Worked example (synthetic, sandbox)

{
  "resourceType": "Bundle",
  "type": "batch",
  "meta": { "tag": [{ "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason", "code": "HTEST" }] },
  "entry": [{
    "resource": {
      "resourceType": "Encounter", "id": "syn-enc-1", "meta": { "versionId": "1", "lastUpdated": "2026-09-14T12:02:14Z" },
      "status": "arrived",
      "class": { "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "EMER" },
      "identifier": [{ "system": "urn:example:visit", "value": "SYN3000123" }],
      "period": { "start": "2026-09-14T08:02:11-04:00" },
      "location": [{ "location": { "reference": "Location/edwr", "display": "Waiting room" }, "status": "active" }]
    },
    "request": { "method": "PUT", "url": "Encounter/syn-enc-1" }
  }]
}

This produces encounter.arrived at 08:02:11 in the waiting room.

Related

• FHIR implementation guide
• SMART on FHIR
• HL7 v2