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.
- 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.
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
.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 theclient_id
). - 4.1upHealth begins collecting data and makes it available to your application.
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.
curl -X GET https://api.1up.health/dstu2/Patient \
-H "Authorization: Bearer accesstokenaccesstoken"
curl -X GET https://api.1up.health/version/Observation
-H "Authorization: Bearer accesstokenaccesstoken"
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"
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 anaccess_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.
Last modified 6mo ago