Connect to Health Systems

1upHealth allows users to seamlessly connect to data from health systems. As a developer, you can read your users' clinical health data from patients who are using your app. We believe data from external health systems is a vital, missing piece to improve care and reducing costs. Data from other clinics and hospitals fills in this gap.

Overview

1) Your app must direct users to the 1upHealth connect API url to link a specific health system. 2) The user will see the systems authentication screen and allow access to their data. 3) Next, the user is redirected back to your app redirect_uri. 1upHealth syncs data from that system into that user's FHIR resources via a backend process every 2 minutes. 4) Your app can query that user's resources which are stored in the FHIR format as normal.

Supported Health Systems

Currently 1upHealth supports over 10,000 health systems. You can find the full list by querying the endpoint here. Use clinical for clinical data from 1upHealth supported health systems.

curl -XGET 'https://api.1up.health/connect/system/clinical?client_id=clientidclientidclientid&client_secret=clientsecretclientsecret'

Content from that response will contain the ids of the health systems.

How to connect

Before you can connect users to health systems, you must create a user via the 1upHealth user management API. Application developers that want to programmatically direct users to connect health systems must send users to the following url, and pass the user's access token and your app's client id in as params.

https://api.1up.health/connect/system/clinical/healthsystemid?client_id=clientidclientidclientid&access_token=accesstokenaccesstoken

For example direct users to this url for Epic test site.

https://api.1up.health/connect/system/clinical/4706?client_id=clientidclientidclientid&access_token=accesstokenaccesstoken

As the user follows that link, 1upHealth will redirect them to the OAuth2 authorization page for the health system. The user will enter their credentials and then 1upHealth will be given an access token for that user. We will direct that user back to your app's redirect_uri (associated with the client_id). And we will begin collecting data from that health system and making it available to your application.

Accessing the connected data

Clinical data will automatically flow into the FHIR API. Clinical data from health systems will be stored as their native FHIR resources. 1upHealth will keep data in sync with the source systems within a 2 minute time frame. Apps can access data to a specific user by passing in an authorization bearer access_token for that user. Additionally, apps can modify their query to adjust which source metric or they want data from. Here are a few examples. Each of these queries will have to be accompanied by the Authorization header containing the user's bearer auth token.

Query new clinical data using the same access token (or new access token if the original expired) from above.

curl -X GET https://api.1up.health/fhir/dstu2/Patient \
  -H "Authorization: Bearer accesstokenaccesstoken"

List Observations

curl -X GET https://api.1up.health/fhir/version/Observation
  -H "Authorization: Bearer accesstokenaccesstoken"

Query by measured metric

We use LOINC codes to identify measurements like steps (66334-4).

curl -X GET https://api.1up.health/fhir/version/Observation?code=29308-4
  -H "Authorization: Bearer accesstokenaccesstoken"

Connecting an External System: Start to finish

First, list the health systems you want to connect to.

curl -XGET 'https://api.1up.health/connect/system/clinical?client_id=clientidclientidclientid&client_secret=cclientsecretclientsecret'

Let's choose EPIC's test FHIR endpoint with id 4706

Now create a new user

curl -XPOST 'https://api.1up.health/user-management/v1/user?app_user_id=yourappuserid&client_id=clientidclientidclientid&client_secret=clientsecretclientsecret'
  {"success":true,"code":"authcodeauthcodeauthcode","oneup_user_id":123,"app_user_id":"yourappuserid","active":true}

Use your user's code to get an access_token via 1upHealth's OAuth2 token endpoint.

curl -X POST https://api.1up.health/fhir/oauth2/token \
  -d "client_id=clientidclientidclientid" \
  -d "client_secret=clientsecretclientsecret" \
  -d "code=authcodeauthcodeauthcode" \
  -d "grant_type=authorization_code"

{"refresh_token":"refreshtokenrefreshtoken","token_type":"bearer","access_token":"aaccesstokenaccesstoken","expires_in":7200}

Now direct your user to the following url so they can authorize the EPIC app.

https://api.1up.health/connect/system/clinical/4706?client_id=clientidclientidclientid&access_token=accesstokenaccesstoken

For testing purposes, use this username / password combo: fhirjason / epicepic1, and authorize your app. After authorization, the user will be sent back to your app.

In a few moments, the 1upHealth backend process will have pulled in the connected systems data into your user's permissions. You can then use your user's access_token to query their demographics.

curl -X GET https://api.1up.health/fhir/dstu2/Patient \
  -H "Authorization: Bearer accesstokenaccesstoken"

Or query their conditions for a specific code

curl -X GET https://api.1up.health/fhir/dstu2/Condition?code=3928002 \
  -H "Authorization: Bearer accesstokenaccesstoken"

Or make any other FHIR query against the resources that may have been pulled in. Use this same process to link any health system's data with your users.