Export Population-Level Data for a Group

Before you can export population-level data for a group, you must first create a group resource. After you create your group resources, you can export the population-level data for the members of the group. To export the data, you request a list of files that you can use to retrieve the data. You can then call the endpoint for each file to download the data for the group. You can also apply search parameters to your request to specify the start date for the data and the type of resources to include in the response.

After you get access to the FHIR Server and get your access token (Bearer token), you can use your access token to send a GET request or an EXPORT request to the 1up FHIR Server using the Bearer token method.

You can submit an EXPORT request for data for all FHIR resources or for a specific resource type. The base URL for all EXPORT requests at the population level is https://gateway.1up.health/v1/<customer-name>/.

You can use this base URL for the population-level endpoint with any of the other FHIR API requests.

Population-level export supports only GET and EXPORT requests to the 1up FHIR Server. PUT requests are supported only to retry a failed job. POST and DELETE requests are not supported.

If you try to submit a POST or DELETE request to the population-level endpoint, you'll receive a 403 error response.

Create a Group Resource

The first step in the process to export population-level bulk data for a group is to create a group for the member population of FHIR resources that you want to export.

Before you create your member group, it’s important to consider how many resources you want to export. Each member group can contain a maximum of 10,000 members.

Though the FHIR specification includes attributes (period and inactive) that you can specify to determine whether the members you include in a group still belong to the group, the export operation ignores those attributes. If a patient is included in the member array, data for that patient is included in the exported files. Make sure to consider this when you create your group resources.

Before you begin the process to create a group, we recommend that you review the HL7 FHIR R4 information about Resource Groups and how to format a member array in the group.

Create a group:

  1. Create a group list that follows the JSON format specified in the FHIR R4 Resource Group example.

    {
      "resourceType": "Group",
      "id": "102",
      "text": {
        "status": "additional",
        "div": 
            "<div xmlns=\"http://www.w3.org/1999/xhtml\">\n      
                <p>Selected Patients</p>\n      
                <ul>\n        
                    <li>Patient John Doe @ Example Healthcare, Inc. MR = 654321</li>\n        
                    <li>Patient Jane Doe @ Example Healthcare, Inc. MR = 123456</li>\n        
                    <li>Patient Liam Leigh @ Example Healthcare, Inc. MR = 123457, DECEASED</li>\n        
                    <li>Patient Liam Leigh @ Example Healthcare, Inc. MR = 123458, DECEASED</li>\n      
                </ul>\n    
            </div>"
      },
      "type": "person",
      "actual": true,
      "member": [
        {
          "entity": {
            "reference": "Patient/pat1"
          },
          "period": {
            "start": "2014-10-08"
          }
        },
        {
          "entity": {
            "reference": "Patient/pat2"
          },
          "period": {
            "start": "2015-04-02"
          },
          "inactive": true
        },
        {
          "entity": {
            "reference": "Patient/pat3"
          },
          "period": {
            "start": "2015-08-06"
          }
        },
        {
          "entity": {
            "reference": "Patient/pat4"
          },
          "period": {
            "start": "2015-08-06"
          }
        }
      ]
    }

  2. Add a member array to the group and add members (patients) to the array.

    You can add a maximum of 10,000 members to the array.

    "member": [
        {
          "entity": {
            "reference": "Patient/memberID123" }
    },
    { "entity": { 
       "reference": "Patient/memberID456" }
    },

  3. Give the completed group JSON array to 1upHealth to create your group of patients on the 1up Platform.

After your group is created on the 1up Platform, you can export population-level data for the group.

Export Population-Level Bulk Data for the Group

After you create your group resources, you can export the bulk data for the members of the group. To export the data, you request a list of files that you can use to retrieve the data. You can then call the endpoint for each file to download the data for the group. You can also apply search parameters to your request to specify the start date for the data and the type of resources to include in the response.

Before you begin, make sure that you have your access token. If you don't already have an access token, follow the steps in Get Access to the 1upHealth FHIR Server to get your access token.

Search Parameters

You can apply the following search parameters to your request to filter the results by resource type or date.

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

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

Example:
https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/Group/<ID>/$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

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

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

Get the Download Files List

You can send a request to the endpoint to get the list of download files to use to retrieve the bulk data that you exported using the FHIR $export operator. You can then use the download files to get the group bulk data from the export endpoint.

You must use the token-authentication method to get the list of files. The client header request option is not supported. If you don't already have an access token, follow the steps in Get Access to the 1upHealth FHIR Server to get your access token

For more information about access tokens, see Authentication & Authorization APIs.

For all of the example commands, make sure that you replace the <company-name> and <ID> placeholder text in the request with the correct company name and group ID values.

Before you execute this request, make sure that you have authenticated with your access token.

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

After you submit your request, the list of download files is returned.

Execute the Group Bulk Export Process

You can use the list of download files you retrieved to connect to the 1upHealth group export endpoint and export the group bulk data for the members you added to your group.

If you change the group resource that includes the patient list (member IDs), you must execute the bulk export operation again to capture the changes in the group.

The following example request exports all FHIR resources for the specified 1upHealth customer using the base URL with bulk-export/bulk-data and $export included in the URL.

  • URL format

    https://gateway.1up.health/v1/<customer-name>/bulk-export/bulk-data/r4/Group/<ID>$export

  • URL example

    https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/Group/123456/$export

  1. Call the group export endpoint. Run:

    GET https://gateway.1up.health/v1/<company-name>/bulk-export/bulk-data/r4/Group/<ID>/$export

  2. Call the endpoint for each file that you want to download.

    Make sure to include any search parameters in your call request.

    You receive a response with the set of links to the Newline Delimited JSON (NDJSON) files for each of the FHIR resource types.

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

Download Population-Level Data Exported for a Group

After you execute the population-level bulk export for the group, you can use the links to the Newline Delimited JSON (NDJSON) files for each of the FHIR resource types to download the NDJSON files and consume the data. Each NDJSON link in the response contains only one FHIR resource type, but can contain thousands of individual FHIR resources. There can also be multiple NDJSON links for a single resource type if the size of the data set requires multiple files.

Before you download the contents of the NDJSON files, make sure that you have authenticated using your access token. The client header request option is not supported. If you don't already have an access token, follow the steps in Get Access to the 1upHealth FHIR Server to get your access token

For more information about access tokens, see Authentication & Authorization APIs.

To download the contents of an NDJSON file, go to the link in the response.

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