Implement FHIR Bulk Data $import to ingest NDJSON resources into a FHIR server asynchronously
domain: hl7.org/fhir · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Construct a $import operation request body as a JSON manifest containing an inputFormat of application/fhir+ndjson, an inputSource URL, and a storageDetail object describing where the source files are located
Include an input array in the manifest where each entry specifies the FHIR resource type and a URL pointing to the NDJSON file for that type
POST the manifest to [fhir-base]/$import with Content-Type: application/json and Prefer: respond-async
Receive the 202 Accepted response and extract the Content-Location header to obtain the polling endpoint for this import job
Poll the Content-Location URL until a 200 response is received, then inspect the response body for per-resource import counts and any error entries describing resources that failed to import
Known gotchas
The $import operation is not yet a finalized FHIR standard as of R4 — server support is highly variable and implementations may use vendor-specific request formats; always verify the server's CapabilityStatement or documentation before attempting $import
Source NDJSON files must be accessible to the FHIR server (e.g., a shared storage location or pre-signed cloud storage URL) — the server fetches the files server-side and cannot access URLs that are only reachable from the client network
Resource references within imported NDJSON files may use logical IDs that do not yet exist on the target server; some servers resolve references during import while others leave dangling references, requiring a post-import integrity check
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?