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 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 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.
// curl -XPOST 'https://api.1up.health/connect/system/clinical' -d '{"client_id":"xxxxxxxxxxxx","client_secret":"xxxxxxxx","systemType":"HealthSystem"}' -H 'Content-Type:application/json'
Content from that response will contain the ids of the health systems. A single entry from that response will look like this
{
    "id": 11049,
    "name": "",
    "resource_url": "https://fhir.healow.com/FHIRServer/fhir/EHEDBD",
    "logo": "https://1uphealth-assets.s3-us-west-2.amazonaws.com/systems/health-system-default.png",
    "api_version": "FHIR STU3 3.0.1",
    "status": "connection_working",
    "ehr": "eClinicalWorks",
    "locations": [
        {
            "name": "",
            "address": {
                "line": [
                    "55 Fruit St",
                    ""
                ],
                "city": "Boston",
                "postalCode": "02114",
                "state": "MA"
            }
        }
    ]
}
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.
https://api.1up.health/connect/system/clinical/{healthsystemid}?client_id=clientidclientidclientid&access_token=accesstokenaccesstoken
For example direct users to this url for Michigan Medicine.
https://api.1up.health/connect/system/clinical/4894?client_id=clientidclientidclientid&access_token=accesstokenaccesstoken
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. 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/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"
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'
Sample Response:
{
    "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://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
}
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/dstu2/Patient \
  -H "Authorization: Bearer accesstokenaccesstoken"
Or query their conditions for a specific code
curl -X GET https://api.1up.health/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.
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 url
https://api.1up.health/connect/system/clinical/4706?client_id=clientidclientidclientid&access_token=accesstokenaccesstoken&state=xyz
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 7d ago