Bulk Data Export

FHIR Bulk Data Export

Oystehr FHIR API implements Group-level data export described in Bulk Data Access IG 2.0.0 (opens in a new tab). An export request triggered on a Group resource will result in exporting all members of the Group as well as all resources which belong to a compartment of any Patient which is a member of a Group. Single patient export can be performed with an export of a Group which contains only the desired patient. Exported data will be available in NDJSON (opens in a new tab) format.

Typical export workflow

  1. Get an access token to be able to call Oystehr's FHIR API.
  2. Make a request to /Group/[id]/$export.
  3. The response will contain Content-Location header with an URL for getting status of the export request.
  4. Periodically make a request to the "export status" URL to check if the export is still in-progress or finished.

Start export

Request

curl --location 'https://fhir-api.zapehr.com/r4/Group/[id]/$export' \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'x-zapehr-project-id: <your_project_id>'

There is an optional _since parameter which forces to export resources updated after a certain point in time only.

Response

  • 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 in JSON format

Export status

Request

curl --location 'https://fhir-api.zapehr.com/r4/export/job/[id]' \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'x-zapehr-project-id: <your_project_id>'

Response

  • In-Progress
Status: 202 Accepted
X-Progress: “50% complete”
Retry-After: 120
  • Error
Status: 500 Internal Server Error
Content-Type: application/fhir+json

{
 "resourceType": "OperationOutcome",
 "id": "1",
 "issue": [
  {
   "severity": "error",
   "code": "processing",
   "details": {
    "text": "An internal timeout has occurred"
   }
  }
 ]
}
  • Complete
Status: 200 OK
Expires: Mon, 22 Jul 2019 23:59:59 GMT
Content-Type: application/json

{
 "transactionTime": "2021-01-01T00:00:00Z",
 "request" : "https://example.com/fhir/Patient/$export?_type=Patient,Observation",
 "requiresAccessToken" : true,
 "output" : [{
  "type" : "Patient",
  "url" : "https://example.com/output/patient_file_1.ndjson"
 },{
  "type" : "Patient",
  "url" : "https://example.com/output/patient_file_2.ndjson"
 },{
  "type" : "Observation",
  "url" : "https://example.com/output/observation_file_1.ndjson"
 }],
 "deleted" : [{
  "type" : "Bundle",
  "url" : "https://example.com/output/del_file_1.ndjson"
 }],
 "error" : [{
  "type" : "OperationOutcome",
  "url" : "https://example.com/output/err_file_1.ndjson"
 }],
 "extension":{"https://example.com/extra-property": true}
}

Cancel/Delete an export

Request

curl --location 'https://fhir-api.zapehr.com/r4/export/job/[id]' \
     --request DELETE
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'x-zapehr-project-id: <your_project_id>'

Response

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