Export Bulk Data at the Population Level

You can use the FHIR® Bulk Data APIs ($export operator) to transfer data and analyze data at the population level using a synchronous workflow.

To retrieve a list of bulk data files for your client application that you can download, you can submit a request to the analytics bulk-data endpoint with the FHIR Export operator ($export).

Bulk Export with an Access Token

Use this endpoint to export bulk data for a given 1up user using the FHIR® Export operator ($export) . This initial request returns a list of download files, which can be individually requested to retrieve the data.

This request relies on having an Access Token obtained using Auth APIs (first get an authorization code, then exchange for an access token for a 1up user).

curl --location --request GET 'https://gateway.1up.health/v1/<company-name>/bulk-export/bulk-data/r4/Group/<ID>/$export' \
--header 'Authorization: Bearer <accessToken>'
curl --location --request GET 'https://gateway.1up.health/v1/<company-name>/bulk-export/bulk-data/r4/$export' \
--header 'Authorization: Bearer <accessToken>'

Export Search Parameters

For FHIR R4, 1up supports the following search parameters for the Export operator ($export).

Parameter

Description

Format

_type

Specify the types of resources to include in the response.

_type applies only to the Patient and applicable Patient Compartment resources.

Example: _type=Encounter returns only Encounter resources

Group format: https://gateway.1up.health/v1/<company-name>/bulk-export/bulk-data/r4/Group/<ID>/$export?_type=Encounter

Group example:
https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/Group/<ID>/$export?_type=Encounter

Client ID format: https://gateway.1up.health/v1/<company-name>/bulk-export/bulk-data/r4/$export?_type=Encounter

Client ID example: https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/$export?_type=Encounter

_since

Resources are included in the response if their state has changed after the specified date.

Example: Resource.meta.lastUpdated is later than the specified _since value

Group format: https://gateway.1up.health/v1/<company-name>/bulk-export/bulk-data/r4/Group/<ID>/$export?_since=YYYY-MM-DD

Group example:
https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/Group/<ID>/$export?_since=2021-01-01

Client ID format: https://gateway.1up.health/v1/<company-name>/bulk-export/bulk-data/r4/$export?_since=YYYY-MM-DD

Client ID example: https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/$export?_since=2021-01-01

 

"output": [
{
"type": "AllergyIntolerance",
"url": "https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/$export/AllergyIntolerance/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdGFydCI6ImU0NiIsInRvdGFsIjo0LCJ1c2VySWQiOiIxMjM2NzUwNDkifQ.aOqtYWB9Xaup4R80pGjjl4gyaQV9SXRmZaqmnBHp2oI.ndjson"
},
{
"type": "Condition",
"url": "https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/$export/Condition/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdGFydCI6ImU0NiIsInRvdGFsIjoxMjAxLCJ1c2VySWQiOiIxMjM2NzUwNDkifQ.LcsXvPEnC0vNr1OwIUi4j98qjRxbT-99dr739r7mjrE.ndjson"
},
{
"type": "Procedure",
"url": "https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/$export/Procedure/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdGFydCI6ImU0NiIsInRvdGFsIjoxMywidXNlcklkIjoiMTIzNjc1MDQ5In0.2qEoEMEzMng0ws33jvWzqLfLQnstluA2BbkDAd1605U.ndjson"
},
{
"type": "MedicationOrder",
"url": "https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/$export/MedicationOrder/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdGFydCI6ImU0NiIsInRvdGFsIjo0MSwidXNlcklkIjoiMTIzNjc1MDQ5In0.NdLjPwLte_tvWN5nnaA5YMGw11NrKP_gd6mzXDTeII4.ndjson"
},
{
"type": "MedicationStatement",
"url": "https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/$export/MedicationStatement/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdGFydCI6ImU0NiIsInRvdGFsIjo1MywidXNlcklkIjoiMTIzNjc1MDQ5In0.2M1jLqkjN6uR3L9ISsWsJr5S8aj_rNannoHVC2iiEzU.ndjson"
},
{
"type": "Immunization",
"url": "https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/$export/Immunization/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdGFydCI6ImU0NiIsInRvdGFsIjo0LCJ1c2VySWQiOiIxMjM2NzUwNDkifQ.aOqtYWB9Xaup4R80pGjjl4gyaQV9SXRmZaqmnBHp2oI.ndjson"
},
{
"type": "Observation",
"url": "https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/$export/Observation/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdGFydCI6ImU0NiIsInRvdGFsIjo0MTYsInVzZXJJZCI6IjEyMzY3NTA0OSJ9.9MzsFPH0aWs85fuiFPv7TTSZftbQ2uYqZB1mrvgD_b8.ndjson"
},
{
"type": "DiagnosticReport",
"url": "https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/$export/DiagnosticReport/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdGFydCI6ImU0NiIsInRvdGFsIjozLCJ1c2VySWQiOiIxMjM2NzUwNDkifQ.Fpgzt5vbwdtj8ngj7YuOZ_ngZnwZSr0dQunZIrK05c4.ndjson"
},
{
"type": "Patient",
"url": "https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/$export/Patient/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdGFydCI6ImU0NiIsInRvdGFsIjoxLCJ1c2VySWQiOiIxMjM2NzUwNDkifQ.aiEJoxsOPrr3QMmgVmV2AWUXKIxhREElfFSCHUpRuks.ndjson"
},
{
"type": "RelatedPerson",
"url": "https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/$export/RelatedPerson/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdGFydCI6ImU0NiIsInRvdGFsIjoyLCJ1c2VySWQiOiIxMjM2NzUwNDkifQ.tFsPhGTH_LxHwSY8eE9i_DHU9hrxBcFYMjGi5MsjEuU.ndjson"
},
{
"type": "Encounter",
"url": "https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/$export/Encounter/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdGFydCI6ImU0NiIsInRvdGFsIjo0OCwidXNlcklkIjoiMTIzNjc1MDQ5In0.SlnbTyNdWuT_-k_RGHVn6ytWpDrrucuq71FeYvjQijs.ndjson"
},
{
"type": "DocumentReference",
"url": "https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/$export/DocumentReference/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdGFydCI6ImU0NiIsInRvdGFsIjoyODAsInVzZXJJZCI6IjEyMzY3NTA0OSJ9.txQ-_wmL9ybXMrLMprpQZ3heYbsvKYmhHODJQHbzWlI.ndjson"
}
]
}

Handling the NDJSON Response

The response to your export request contains a set of links to Newline Delimited JSON (NDJSON) files for the various FHIR resource types. Each NDJSON link in the response contains only one FHIR resource type, but can contain thousands of individual FHIR resources. Depending on how much data is exported, there can be multiple NDJSON links for a single resource type.

To get access the NDJSON files, you must have an access token. You can inject an access token using API test tools such as Postman or cURL. For more information about how to get an access token, see Get Access to the 1upHealth FHIR Server.

To consume the NDJSON contents, you can follow one of the links in the response using your an access token.

curl --location --request GET 'https://gateway.1up.health/v1/<company-name>/bulk-export/bulk-data/r4/Group/<ID>/$export/AllergyIntolerance/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdGFydCI6ImU0NiIsInRvdGFsIjo0LCJ1c2VySWQiOiIxMjM2NzUwNDkifQ.aOqtYWB9Xaup4R80pGjjl4gyaQV9SXRmZaqmnBHp2oI.ndjson' \
--header 'Authorization: Bearer {accessToken}'