Skip to main content


FHIR OperationDefinition

This operation allows FHIR R4 data to be imported into the server, making it available for query via other operations such as search, aggregate and extract. This operation accepts the NDJSON format, and links to retrieve that data are provided rather that sending the data inline within the request itself. This is to allow for large data sets to be imported efficiently.

Currently Pathling supports retrieval of NDJSON files from Amazon S3 (s3://), HDFS (hdfs://) and filesystem (file://) URLs. Authentication is supported for S3, see Configuration for details.

Import sources must be explicitly whitelisted within the configuration, for security reasons. See the Import section of the configuration documentation for details.

There are a number of configuration values that affect the encoding of resources imported by this operation, see the Encoding section of the configuration documentation for details.


The import operation supports the Asynchronous Request Pattern, which allows you to kick off a long-running request and check on its progress using a status endpoint.

POST [FHIR endpoint]/$import

Import Import


The request for the $import operation is a Parameters resource containing the following parameters:

  • source [1..*] - A source FHIR NDJSON file containing resources to be included within this import operation. Each file must contain only one type of resource.
    • resourceType [1..1] (code) - The base FHIR resource type contained within this source file. Code must be a member of
    • url [1..1] (uri) - A URL that can be used to retrieve this source file.
    • mode [0..1] (code) - A value of overwrite will cause all existing resources of the specified type to be deleted and replaced with the contents of the source file. A value of merge will match existing resources with updated resources in the source file based on their ID, and either update the existing resources or add new resources as appropriate. The default value is overwrite.


The response from the $import operation is an OperationOutcome resource, which will indicate success or a description of any errors that occurred.


Check out example import requests in the Postman collection:

Run in Postman