Bulk Export

The FHIR Bulk Export mechanism is intended to enable properly authorized and authenticated clients to work with larger FHIR datasets representing multiple patients.

FHIR Bulk Export is authenticated using Backend Services Authorization and happens in three steps:

Client requests a bulk-data export,
Client receives status information regarding progress in the generation of the requested files,
Client retrieves the requested files.

Step 1 - Export a Group of Patients

The first operation initiates the asynchronous generation of data to which the client is authorized for a group of patients.
(See also API Reference - Group/{id}/$export)

Request

GET [fhir base URL]/Group/[id]/$export

Optional Parameters

Name	Type	Description
_since	date	Resources updated after this period will be included in the response. If this parameter is absent only resources created or updated in the past 24 hours will be exported.
_type	string	A string of comma-delimited FHIR resource type to be included in the response. If this parameter is omitted, the server returns all supported resources within the scope of the client authorization.

Responses

Success

HTTP Status Code of 202 Accepted
Content-Location header with the absolute URL of an endpoint for subsequent status requests (polling location)
Optionally, a FHIR OperationOutcome resource in the body

Error (e.g., unsupported search parameter)

HTTP Status Code of 4XX or 5XX
The body is a FHIR OperationOutcome resource in JSON format

Step 2 - Status Request

After a bulk data request has been started, the client can poll the status URL provided in the Content-Location response header of the $export request (Step 1).

Request

GET [polling content location]

Responses

In Progress

HTTP Status Code of 202 Accepted
X-Progress header with a text description of the status of the request

Error

HTTP Status Code of 4XX or 5XX
Content-Type header of application/json
The body is a FHIR OperationOutcome resource in JSON format

Complete

HTTP Status Code of 200 Ok
Content-Type header of application/json
A body containing a JSON object providing metadata and links to the generated bulk data files.

{
    "transactionTime": "[instant]",
    "request" : "[base]/Patient/$export?_type=Patient,Observation",
    "requiresAccessToken" : true,
    "output" : [{
      "type" : "Patient",
      "url" : "http://serverpath2/patient_file_1.ndjson"
    },{
      "type" : "Patient",
      "url" : "http://serverpath2/patient_file_2.ndjson"
    },{
      "type" : "Observation",
      "url" : "http://serverpath2/observation_file_1.ndjson"
    }],
    "error" : [{
      "type" : "OperationOutcome",
      "url" : "http://serverpath2/err_file_1.ndjson"
    }],
    "extension":{"http://myserver.example.org/extra-property": true}
  }

Cancelling an Export Request

If needed, after a bulk data request has been started, a client can send a delete request to the URL provided in the Content-Location header (Step 1). to cancel the request.

Request

DELETE [polling content location]

Responses

Success

HTTP Status Code of 202 Accepted
Optionally a FHIR OperationOutcome resource in the body

Error

HTTP status code of 4XX or 5XX
The body is a FHIR OperationOutcome resource in JSON format

Step 3 - File Retrieval

Using the URLs supplied by the FHIR server in the Complete Status response body (Step 2), the client can download the generated bulk data files (one or more per resource type). The file is returned in newline-delimited JSON format (NDJSON).

{"id":"5c41cecf-cf81-434f-9da7-e24e5a99dbc2","name":[{"given":["Brenda"],"family":["Jackson"]}],"gender":"female","birthDate":"1956-10-14T00:00:00.000Z","resourceType":"Patient"}
{"id":"3fabcb98-0995-447d-a03f-314d202b32f4","name":[{"given":["Bram"],"family":["Sandeep"]}],"gender":"male","birthDate":"1994-11-01T00:00:00.000Z","resourceType":"Patient"}
{"id":"945e5c7f-504b-43bd-9562-a2ef82c244b2","name":[{"given":["Sandy"],"family":["Hamlin"]}],"gender":"female","birthDate":"1988-01-24T00:00:00.000Z","resourceType":"Patient"}

Request

GET [url from status request output field]

Responses

Success

HTTP status of 200 OK
Content-Type header application/fhir+ndjson
Body of FHIR resources in newline delimited json

Error

HTTP Status Code of 4XX or 5XX

See it in action

A publicly available Bulk Data client is available here.