Comment on page
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. 
Data from external health systems is a vital, missing piece that's required to improve care and reduce costs. Data from other clinics and hospitals fills this gap. 
To get OAuth client keys for the 1upHealth API, you can create an account.
Overview
Your app must direct users to the 1upHealth Connect API URL to link to a specific health system.
Users will see the systems authentication screen and can then allow access to their data.
User are redirected back to your app redirect_uri. 1upHealth retrieves data from that system into that user's FHIR® resources.
Your app can query that user's resources which are stored in the FHIR® format as normal.
Get a List of Supported Health Systems
1upHealth supports hundreds of health systems. You can find the full list by querying the following endpoint. Results are returned in increments of 20. Specify offset to set your starting point.
curl -H "Authorization: Bearer {access_token}" -X POST "https://system-search.1up.health/api/search?offset=20"
Content from the response contains the IDs of the health systems. The following is an example of a single entry from that response:
{
        "id":4894,
        "name":"Michigan Medicine",
        "address": "1500 E Medical Center Dr Ann Arbor MI 48109 "
    }
You can use the ID from the response for future requests. In this example, the ID is 4894.
Connect Users
Before you can connect users to health systems, you must use the 1upHealth user management API to create a user. Application developers that want to programmatically direct users to connect health systems must send users to the following URL. 
Make sure to include the user's access token and your app's client ID as params.
https://api.1up.health/connect/system/clinical/{healthsystemid}?client_id=clientidclientidclientid&access_token=accesstokenaccesstoken
This example shows how to direct users for Michigan Medicine.
https://api.1up.health/connect/system/clinical/4894?client_id=clientidclientidclientid&access_token=accesstokenaccesstoken&fhirVersion=FHIR_VERSION
If you include the fhirVersion parameter, only valid FHIR versions supported by that system will retrieve FHIR resources.  

When a user follows the link, the following process occurs.
1.1upHealth redirects the user to the OAuth2 authorization page for the clinical system. 
2.The user enters their credentials for the health system. 
To test the process, you can use these test credentials for health systems that use FHIR.  
3.1upHealth receives an access token for that user, and directs the user back to your app's redirect_uri (associated with the client_id). 
4.1upHealth begins collecting data and makes it available to your application.
Access the Connected Data
Clinical data will automatically flow into the FHIR® API and will be stored as their native FHIR® resources. Apps can access data for a specific user by passing in an authorization bearer access_token for that user. Apps can modify their query to adjust which source metric they want data from. 
The following are a few examples of app queries. Each query must be accompanied by the Authorization header that contains the user's bearer auth token.
Query new clinical data using the same access token (or a new access token if the original expired) from above
curl -X GET https://api.1up.health/dstu2/Patient \
  -H "Authorization: Bearer accesstokenaccesstoken"
List observations
curl -X GET https://api.1up.health/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/version/Observation?code=29308-4
  -H "Authorization: Bearer accesstokenaccesstoken"
Connect an External System
To connect to an external system, you must complete the following steps. You can use this  process to link any health system's data with your users.
1.List the health systems you want to connect to.
This example uses Epic's test FHIR® endpoint with the ID 4706.
curl -H "Authorization: Bearer {access_token}" -X POST "https://system-search.1up.health/api/search?offset=20"
2.Create a new user.
curl -XPOST 'https://api.1up.health/user-management/v1/user?app_user_id=yourappuserid&client_id=clientidclientidclientid&client_secret=clientsecretclientsecret'
Sample response:
{
    "success":true,
    "code":"authcodeauthcodeauthcode",
    "oneup_user_id":123,
    "app_user_id":"yourappuserid",
    "active":true
}
3.Use your user's code to get an access_token from 1upHealth's OAuth2 token endpoint.
curl -X POST https://auth.1up.health/oauth2/token \
  -d "client_id=clientidclientidclientid" \
  -d "client_secret=clientsecretclientsecret" \
  -d "code=authcodeauthcodeauthcode" \
  -d "grant_type=authorization_code"
Sample response:
{
    "refresh_token":"refreshtokenrefreshtoken",
    "token_type":"bearer",
    "access_token":"aaccesstokenaccesstoken",
    "expires_in":7200
}
4.Send your user to the following URL to authorize the Epic app.
https://api.1up.health/connect/system/clinical/4706?client_id=clientidclientidclientid&access_token=accesstokenaccesstoken
For testing purposes, give the user this username / password: fhirjason / epicepic1 to authorize your app. After the app is authorized, the user is sent back to your app.
The 1upHealth backend process retrieves the connected systems data into your user's permissions. This process can take a few moments to complete.
You can then use your user's access_token to query that user's demographics.
curl -X GET https://api.1up.health/dstu2/Patient \
  -H "Authorization: Bearer accesstokenaccesstoken"
You can also query their conditions for a specific code:
curl -X GET https://api.1up.health/dstu2/Condition?code=3928002 \
  -H "Authorization: Bearer accesstokenaccesstoken"
You can make any other FHIR® query against the resources that might have been pulled for that user. 
Connect (Patient) Reference
Next - APIs
FHIR
Last modified 6mo ago