Getting Started
APIs
Connect (Patient) Guide
1upHealth allows users to connect data within health system electronic health records. 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 and data from other clinics and hospitals fills in this gap. If you would like OAuth client keys to the 1upHealth API create an account.
Overview
- Your app must direct users to the 1upHealth connect API url to link a specific health system.
- The user will see the systems authentication screen and allow access to their data.
- 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. - Your app can query that user's resources which are stored in the FHIR® format as normal.
Get List of Supported Health Systems
Currently 1upHealth supports hundreds of health systems. You can find the full list by querying the endpoint here. Use
clinical for clinical data from 1upHealth supported health systems.1
curl -XGET 'https://api.1up.health/connect/system/clinical?client_id=xxxxxxxxxxxxxxxx&client_secret=xxxxxxxxxxxxxxxx' | json_pp
Copied!
Content from that response will contain the ids of the health systems. A single entry from that response will look like this
1
{
2
"id":4894,
3
"name":"Michigan Medicine",
4
"resource_url":"https://mcproxyprd.med.umich.edu/..."
5
}
Copied!
where you will use the id
4894 in this case for future requests.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.
1
https://api.1up.health/connect/system/clinical/{healthsystemid}?client_id=clientidclientidclientid&access_token=accesstokenaccesstoken
Copied!
For example direct users to this url for Michigan Medicine.
1
https://api.1up.health/connect/system/clinical/4894?client_id=clientidclientidclientid&access_token=accesstokenaccesstoken
Copied!
As the user follows that link, 1upHealth will redirect them to the OAuth2 authorization page for the clinical system. The user will enter their credentials health system. Here are some test credentials for health systems that use FHIR.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 and making it available to your application.Accessing the connected data
Clinical data will automatically flow into the FHIR® API and 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.
1
curl -X GET https://api.1up.health/dstu2/Patient \
2
-H "Authorization: Bearer accesstokenaccesstoken"
Copied!
List Observations
1
curl -X GET https://api.1up.health/version/Observation
2
-H "Authorization: Bearer accesstokenaccesstoken"
Copied!
Query by measured metric
We use LOINC codes to identify measurements like
steps (66334-4).1
curl -X GET https://api.1up.health/version/Observation?code=29308-4
2
-H "Authorization: Bearer accesstokenaccesstoken"
Copied!
Connecting an External System: Start to finish
First, list the health systems you want to connect to.
1
curl -XGET 'https://api.1up.health/connect/system/clinical?client_id=clientidclientidclientid&client_secret=cclientsecretclientsecret'
Copied!
Let's choose EPIC's test FHIR® endpoint with id
4706Now create a new user
1
curl -XPOST 'https://api.1up.health/user-management/v1/user?app_user_id=yourappuserid&client_id=clientidclientidclientid&client_secret=clientsecretclientsecret'
Copied!
Sample Response:
1
{
2
"success":true,
3
"code":"authcodeauthcodeauthcode",
4
"oneup_user_id":123,
5
"app_user_id":"yourappuserid",
6
"active":true
7
}
Copied!
Use your user's
code to get an access_token via 1upHealth's OAuth2 token endpoint.1
curl -X POST https://auth.1up.health/oauth2/token \
2
-d "client_id=clientidclientidclientid" \
3
-d "client_secret=clientsecretclientsecret" \
4
-d "code=authcodeauthcodeauthcode" \
5
-d "grant_type=authorization_code"
Copied!
Sample Response:
1
{
2
"refresh_token":"refreshtokenrefreshtoken",
3
"token_type":"bearer",
4
"access_token":"aaccesstokenaccesstoken",
5
"expires_in":7200
6
}
Copied!
Now direct your user to the following url so they can authorize the EPIC app.
1
https://api.1up.health/connect/system/clinical/4706?client_id=clientidclientidclientid&access_token=accesstokenaccesstoken
Copied!
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.1
curl -X GET https://api.1up.health/dstu2/Patient \
2
-H "Authorization: Bearer accesstokenaccesstoken"
Copied!
Or query their conditions for a specific code
1
curl -X GET https://api.1up.health/dstu2/Condition?code=3928002 \
2
-H "Authorization: Bearer accesstokenaccesstoken"
Copied!
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.
Add an optional state parameter
You can add a state parameter to the url which connects users to a health system.
Let's choose EPIC's test FHIR® endpoint with id
4706 and direct your user to the following url1
https://api.1up.health/connect/system/clinical/4706?client_id=clientidclientidclientid&access_token=accesstokenaccesstoken&state=xyz
Copied!
The state=xyz is stored and passed along with other parameters as JSON Web Token during the flow and is preserved as
client_state_param until redirected to the callback url.Last modified 10mo ago
Copy link
Contents
Overview
Get List of Supported Health Systems
How to connect
Accessing the connected data
Query new clinical data using the same access token (or new access token if the original expired) from above.
List Observations
Query by measured metric
Connecting an External System: Start to finish
Add an optional state parameter