Export Population Data

For Health Plan Partners

1upHealth customers, such as health plans, can allow their authorized health plan partners (such as providers or analytics vendors) to get access to their health plan’s data on the 1up FHIR Server. The partners that the health plan authorizes can then use 1up Exchange to export data at the population level, using a specified client ID.

Before You Begin

Before you start the process to get access to the 1upHealth FHIR Server and export population-level data, make sure that you get the following information from your 1upHealth Customer Success Manager.

  • Customer URL

    The is the unique web address that you use to connect to the 1upHealth FHIR Server to export data.

    The base URL has this format: https://gateway.1up.health/v1/<customer-URL>/

  • Client credentials

    The client ID and client secret that you use to get your access token.

Get Access to the 1upHealth FHIR Server

As a partner of a 1upHealth customer (a health plan), you can get a client ID and client secret (client credentials) from your health plan partner to get access to the 1up FHIR Server and export data at the population level. After you have your client credentials, you can request the access token that you’ll use to export data from the FHIR Server.

You can use Postman to test the following REST API requests before you integrate them into your application.

To get your access token, include your client credentials in the request that you submit to the OAuth 2.0 server.

Get your Access Token

To get your access token, submit the following request.

Make sure to replace the placeholder text with the correct customer URL, client ID, and client secret.

curl --location 'https://gateway.1up.health/auth/realms/<customer-URL>/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=yyy' \
--data-urlencode 'client_secret=xxx' \
--data-urlencode 'grant_type=client_credentials'

The request response includes your access token (Bearer token) and the scopes you can get access to with the token.

Use this access token in your export request to the 1up FHIR Server endpoint.

Export Data at the Population Level

After you 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 with 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-URL>/.

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.

Export All Resources

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-URL>/bulk-export/bulk-data/r4/$export

  • URL example

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

Export a Specific Resource Type

If you only want to get data for a specific FHIR resource type, you can restrict your request to only that resource type. For this request type, you use the base URL and append the name of the resource type to the end of the URL.

  • URL format

    https://gateway.1up.health/v1/<customer-URL>/bulk-export/bulk-data/r4/<resource-type>

  • URL examples

    https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/Patient

    https://gateway.1up.health/v1/ExampleCompany/bulk-export/bulk-data/r4/ExplanationOfBenefit

Verify the Status of the Export Operation

You can send a request to the 1up FHIR Sever Status endpoint to get status updates on the export job.

GET https://{baseURL}/bulk-data/r4/$export/job/<job-ID>