The Context Engine Studio is now open source.  View on GitHub →

Ingest a FHIR Bundle

Send a FHIR R4 or R5 Bundle to a patient.

Send a FHIR Bundle (or any single FHIR resource) to register it against a patient. The patientId in the URL is the patient ID you chose when you created the patient.

The FHIR release is part of the path, because a Bundle does not state which release it is written against. Post R4 payloads to /ingestions/fhir/r4 and R5 payloads to /ingestions/fhir/r5.

Make the request

Create the patient before the first ingest:

bash
curl -X PUT "https://<workspace-id>.w.clinia.cloud/v1/patients/{patientId}" \
  -H "Authorization: Bearer <access-token>"

This call is idempotent. The patientId you pick has to fit the character set for identifiers you assign.

bash
curl -X POST "https://<workspace-id>.w.clinia.cloud/v1/patients/{patientId}/ingestions/fhir/r4" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d @fhir-bundle.json

A successful call answers 202 with a receipt:

json
{
  "ingestionId": "c1m2k3n4p5q6r7s8t9u0v1w2",
  "source": "fhir/r4",
  "mimeType": "application/json",
  "receivedAt": "2026-09-10T14:22:31.004Z",
  "status": "pending",
  "staged": { "facts": 12, "events": 8, "narratives": 1, "messages": 0 },
  "intake": [
    {
      "unit": "resource",
      "received": 42,
      "entries": [
        { "kind": "Condition", "count": 4, "outcome": "structured" },
        { "kind": "Observation", "count": 30, "outcome": "structured" },
        { "kind": "DocumentReference", "count": 1, "outcome": "text_only" },
        { "kind": "ImagingStudy", "count": 7, "outcome": "ignored", "reason": "unsupported" }
      ]
    }
  ],
  "startedAt": null,
  "completedAt": null,
  "failure": null
}

Ingestion continues after the response. Follow the receipt until it settles, as described in Track an Ingestion.

Request details

The body must be a valid FHIR JSON document — either a Bundle or a single resource such as Patient, Condition or MedicationRequest — and Content-Type must be application/json.

Supported resource types include: Patient, Condition, MedicationStatement, MedicationRequest, Observation, AllergyIntolerance, Coverage, Immunization, Procedure, Encounter, FamilyMemberHistory, Device, DeviceUseStatement, DeviceUsage, and DiagnosticReport.

Each call is one submission and one receipt. Multiple calls for the same patientId accumulate sources, and entity resolution re-runs over everything accumulated.

Clinical prose. A DocumentReference contributes no entities. Its text attachment becomes a narrative instead — kept verbatim, readable under /sources/, and adjudicated against the facts it speaks to. The attachment must be inline (data) or a Binary in the same bundle, and one of text/plain, text/html or application/xhtml+xml. A remote url, or any other content type, appears in intake as text_only turning to ignored — so a bundle can carry documents and contribute none of their prose.

Error responses

Validation is synchronous: a body that is not FHIR JSON, or that carries no resource, is rejected before anything is staged.

StatusCause
400Request body is not valid JSON, is missing a resourceType field, or carries no FHIR resource
404No such patient

Follow the submission

Poll the receipt until it settles and check what was not used, as described in Track an Ingestion.

For the resolved picture across every source, walk the graph, as described in Audit the Patient Graph.

Submitting several documents

Each call carries one Bundle, and a Bundle is already a collection — put several resources in one and post it once. For several independent Bundles, make several calls. How that work is divided internally is decided for you, so nothing about the grouping needs to be expressed in the request.

On this page