Get Users
https://api.1up.health/user-management/v1/user
Get the list of all the users that exist inside your 1up Developer Application, with the option of filtering by specific users
Headers
This endpoint receives authentication in the form of a http bearer authentication header.
User successfully retrieved.
{
"oneup_user_id" : "string",
"app_user_id" : "string",
// Indicates whether the user is active or not
"active" : "boolean",
},
Could not find a user matching this query.
{
// would be non-empty if an error occurred during the request
"error" : "string",
},
Create User
https://api.1up.health/user-management/v1/user
Will cause a user to be created with the attributes passed in the request body. The request won't fail if the user already exists but rather will return error saying this user already exists
.
Headers
This endpoint receives authentication in the form of a http bearer authentication header.
Form Data Parameters
1/2 API keys generated in creating a new app.
1/2 API keys generated in creating a new app.
User successfully retrieved.
{
"success" : "boolean",
"code" : "string",
"app_user_id" : "string",
"oneup_user_id" : "string",
"active" : "boolean",
}
Could not find a user matching this query.
{
// would be non-empty if an error occurred during the request
"error" : "string",
}
Update User
https://api.1up.health/user-management/v1/user
Can be used to modify an existing user object. It is possible to modify the app_user_id
, but the oneup_user_id
is assigned when the user is created and cannot be changed.
Form Data Parameters
1/2 API keys generated in creating a new app.
1/2 API keys generated in creating a new app.
User successfully updated.
{
"oneUpUserId" : 123456789,
"success" : true
}
Generate User Authorization Code
https://api.1up.health/user-management/v1/user/auth-code
A backend app can use this endpoint to get a new authorization code for a user. Note that this endpoint should not be called in a browser context because it would require exposing your app's secret key to users. The code received expires in 2 hours (7200 seconds).
Form Data Parameters
1/2 API keys generated in creating a new app.
1/2 API keys generated in creating a new app.
{
"client_id" : "string",
"app_user_id" : "string",
"client_secret" : "string",
}
Returns an authorization 'code', which can be used to exchange for an 'access_token' and 'refresh_token'.
{
"success" : "boolean",
"code" : "string",
"oneup_user_id" : "string",
"app_user_id" : "string",
"active" : "boolean",
}
Generate Access Token
https://api.1up.health/fhir/oauth2/token
A backend app can use this endpoint to exchange the authorization code
for a user for a access_token
, refresh_token
and id_token
. The id_token is only returned if you include the openid
scope when requesting for a code. Note that this endpoint should not be called in a browser context because it would require exposing your app's secret key to users.
Form Data Parameters
Access code is exchanged for the bearer token.
1/2 API keys generated in creating a new app.
1/2 API keys generated in creating a new app.
Returns an access_token, refresh_token and optionally an id_token. The access_token expires in 2 hours (7200 seconds) and you can obtain a new access_token by using the refresh_token or generating a new authorization code.
{
"refresh_token" : "string",
"token_type" : "string",
"access_token" : "string",
"expires_in" : "integer",
"scope" : "string",
"id_token" : "string",
}
Get FHIR® Resources
https://api.1up.health/fhir/{fhirVersion}/{resourceType}
Returns all matching FHIR
Query Parameters
The _content
query parameter enables users to text search against the entire resource in the response bundle. e.g., /fhir/dstu2/Patient?_content=Atul+Gawande
The _count
query parameter enables users to modify the number of resources in each page of the response bundle. The maximum number is 100 resources. e.g., /fhir/dstu2/Patient?_count=10
A paginated FHIR® Bundle containing all the resources that match the query (default is 10 resources per bundle).
{
// See the official hl7 FHIR® docs (https://www.hl7.org/fhir/bundle.html) for more information on how a FHIR® bundle is structured.
// additional attributes will be present depending on the resource posted
"id" : "string",
"resourceType" : "string",
// the entry will contain the fhir resources that match the query
"entry" : [
],
}
Create a FHIR® Resource
https://api.1up.health/fhir/{fhirVersion}/{resourceType}
Can be used to create a FHIR® resource with a given type.
Headers
This endpoint receives authentication in the form of a http bearer authentication header.
A FHIR® Resource containing all the attributes that were posted.
{
// additional attributes will be present depending on the resource posted
"id" : "string",
"resourceType" : "string",
}
Get All User Data
https://api.1up.health/fhir/{fhirVersion}/Patient/{patientId}/$everything
This endpoint returns a list of all known FHIR® resources for a given patient. This is useful when transmitting batch data or getting the full patient history.
Headers
This endpoint receives authentication in the form of a http bearer authentication header.
User data retrieved.
{
// See the official hl7 FHIR® docs (https://www.hl7.org/fhir/bundle.html) for more information on how a FHIR® bundle is structured.
// additional attributes will be present depending on the resource posted
"id" : "string",
"resourceType" : "string",
// the entry will contain the fhir resources that match the query
"entry" : [
],
}
Delete All User Data
https://api.1up.health/fhir/{fhirVersion}/Patient/{patientId}/$everything
This endpoint returns an OperationOutcome resource stating that all the resources for the patient is deleted successfully. This is useful when deleting multiple resource types for a patient at once.
Headers
This endpoint receives authentication in the form of a http bearer authentication header.
An OperationOutcome resource with success message containing patient id in it.
{
// See the official hl7 FHIR® docs (https://www.hl7.org/fhir/bundle.html) for more information on how a FHIR® bundle is structured.
// additional attributes will be present depending on the resource posted
"id" : "string",
"resourceType" : "string",
// the entry will contain the success message information with patient id in it
"issue" : [
],
}
Grant Permission to User
https://api.1up.health/fhir/dstu2/Patient/patientid/_permission/{oneUpUserId}
When making a request to the 1upHealth FHIR® API using a user's access_token
, the resources returned will be scoped to only the resources that the user has permissions to view. However, sometimes when building an app you might want to support the ability for users to grant access to other users to see certain records. This endpoint allows you to grant access to resources to arbitrary users.
Form Data Parameters
1 of 2 API keys generated in creating a new app.
1 of 2 API keys generated in created a new app.
User updated.
{
"oneUpUserId" : 12345,
"success" : true
}
Revoke Permissions From User
https://api.1up.health/fhir/dstu2/Patient/patientid/_permission/oneup_user_id_to_lose_access
This endpoint allows you to remove permissions that have been granted to users to see other users' FHIR® resources.
Headers
This endpoint receives authentication in the form of a http bearer authentication header.
Delete User Permissions.
{
"oneUpUserId" : 12345,
"success" : true
}
Health System UI
https://api.1up.health/connect
A common pattern is to ask the user to connect data from their health system to the app. This endpoint returns a simple html page that can be used as a starting point for walking the user through the data connect flow. For more details, read about the Connect Health Data iFrame.
This endpoint returns an html page and inline css that, when
rendered, results in a UI for selecting which health care system
the user would like to connect. The most common use of this is to
render this endpoint in an iframe within the developers own app.
Search Health Systems
https://api.1up.health/connect/system/provider/search
Used to run a text search on health systems, often for the purpose of allowing the user to find their health system's authorization portal.
Headers
This endpoint receives authentication in the form of a http bearer authentication header.
The result will return a bundle of FHIR® Organizations which
contain the 1upHealth health system id and an extension with
the logo of that org or health system. You can use that to
direct the patient to the correct connect API url so the patient
can authorize sharing of their medical data. See the official
hl7 FHIR® docs (https://www.hl7.org/fhir/bundle.html) for more
information on how a FHIR® bundle is structured.
Get Supported Health Systems
https://api.1up.health/connect/system/clinical
Use this endpoint to query the full list of supported health systems. If your use-case would benefit from full-text search of providers on fields like name, address, or clinician names, then we recommend using the Provider Search endpoint instead.
Query Parameters
health_systems_only
optional
Enter `true` as the value.
Enter name of the health system.
Returns an array of object containing information about health systems.
[
{
"resource_url" : "string",
"id" : "number",
"name" : "string",
"api_version" : "string",
"status" : "string",
"logo" : "string",
// Location contains addresses and name of health system
"locations" : [
],
},
]
Bulk Data Export
https://analytics.1up.health/bulk-data/{fhirVersion}/$export
Use this endpoint to export bulk data for a given 1up user using the FHIR® $export operator. This initial request returns a list of download files, which can be individually requested to retrieve the data.
Path Parameters
Optionally restrict the types of FHIR® resources to export with a comma-separated list of standard FHIR® resource types (e.g. 'Patient,Observation'). Note the request will fail if an invalid resource type is requested.
Headers
This endpoint receives authentication in the form of a http bearer authentication header.
The returned list will include at least one download file for each resource type for which data exists.
{
// a timestamp of the query request
"transactionTime" : "string",
// the original request url
"request" : "string",
// whether downloading the output files will also require using a bearer access token
"requiresAccessToken" : "boolean",
// the resulting list of files to download the exported resources from
"output" : [
{
// the FHIR® resource type contained in the file
"type" : "string",
// the url of the download file
"url" : "string",
},
],
}