Confirm the FHIR server supports bulk import by checking the CapabilityStatement or server documentation; $import is not yet part of the ratified Bulk Data IG (as of the v3.0.0 ballot) but is defined in server-specific or draft proposals — confirm the operation definition URL the server expects
Construct the $import request body as a JSON object listing the input NDJSON files: include 'resourceType' to import (e.g., 'Patient', 'Observation') and the storage URL (e.g., an S3 or Azure Blob presigned URL) where the NDJSON files are accessible
POST the $import request to [base]/$import (system-level) or a server-defined endpoint with the header 'Prefer: respond-async'; the server returns HTTP 202 Accepted with a Content-Location header pointing to a status polling URL
Poll the Content-Location URL with GET requests; the response includes X-Progress (percentage or status text) until the operation completes; on completion the server returns HTTP 200 with a manifest listing imported resource counts and any error files
Download and inspect the error NDJSON file (if provided in the manifest) to identify individual resources that failed to import due to validation errors, duplicate conflicts, or referential integrity issues
After successful import, verify a sample of imported resources are retrievable via standard FHIR read or search operations to confirm the data was correctly stored
Known gotchas
$import is still an emerging/draft operation without a finalized HL7 IG specification as of mid-2026 — implementations vary significantly between server vendors; always consult the server's own $import OperationDefinition rather than assuming a universal request format
NDJSON input files must contain exactly one valid FHIR resource per line with no trailing commas or file-level JSON wrappers; malformed NDJSON causes the entire batch file to fail rather than individual line failures on most servers
Large imports can run for minutes to hours — implement robust polling with exponential back-off and a maximum retry window; do not hold an HTTP connection open for the full import duration
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp