REST API Reference

Get Users
Description

Get the list of all the users that exist inside your 1up Developer Application, with the option of filtering by specific users

Path
GET /user-management/v1/user
Request Body
application/json
{
  "client_id" : "string",
  "client_secret" : "string",
  
  // Add app_user_id or oneup_user_id to filter by specific users
  "app_user_id" : "string",
  "oneup_user_id" : "string",
},
Responses
http status code: 200
An array of user objects
application/json
{
  "oneup_user_id" : "string",
  "app_user_id" : "string",
  
  // Indicates whether the user is active or not
  "active" : "boolean",
},
-or-
{
  
  // would be non-empty if an error occurred during the request
  "error" : "string",
},
Create User
Description

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.

Path
POST /user-management/v1/user
Request Body
application/json
{
  "client_id" : "string",
  "client_secret" : "string",
  "app_user_id" : "string",
},
Responses
http status code: 201
application/json
{
  "success" : "boolean",
  "code" : "string",
  "app_user_id" : "string",
  "oneup_user_id" : "string",
  "active" : "boolean",
},
-or-
{
  
  // would be non-empty if an error occurred during the request
  "error" : "string",
},
Update User
Description

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.

Path
PUT /user-management/v1/user
Request Body
application/json
{
  "client_id" : "string",
  "client_secret" : "string",
  "app_user_id" : "string",
  "oneup_user_id" : "string",
},
Responses
http status code: 200
application/json
{
  "success" : "boolean",
  "oneup_user_id" : "string",
},
-or-
{
  "success" : "boolean",
  "error" : "string",
},
Generate User Authorization Code
Description

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)

Path
POST /user-management/v1/user/auth-code
Request Body
application/json
{
  "client_id" : "string",
  "app_user_id" : "string",
  "client_secret" : "string",
},
Responses
http status code: 200
Returns an user authorization `code`, which can be used to exchange for an `access_token` and `refresh_token`.
application/json
{
  "success" : "boolean",
  "code" : "string",
  "oneup_user_id" : "string",
  "app_user_id" : "string",
  "active" : "boolean",
},
Generate Access Token
Description

A backend app can use this endpoint to exchagne the authorization code for a user for a access_token and refresh_token. Note that this endpoint should not be called in a browser context because it would require exposing your app's secret key to users.

Path
POST /fhir/oauth2/token
Request Body
application/json
{
  "client_id" : "string",
  "client_secret" : "string",
  "code" : "string",
  "grant_type" : "string",
},
Responses
http status code: 200
Returns an access_token and refresh_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.
application/json
{
  "refresh_token" : "string",
  "token_type" : "string",
  "access_token" : "string",
  "expires_in" : "integer",
},
Get FHIR Resources
Description

Returns all matching FHIR resources for a resource type (default is 10 resources per page)

See also:

Path
GET /fhir/{fhirVersion}/{resourceType}
Query Parameters
_count — integer

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=100

Headers

This endpoint receives authentication in the form of a http bearer authentication header.

For example, Authorization: Bearer <user_access_token_here>.

Responses
http status code: 200
A paginated FHIR Bundle containing all the resources that match the query (default is 10 resources per bundle)
application/json
{
  // 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" :   [
  ],
},
-or-
{
  
  // would be non-empty if an error occurred during the request
  "error" : "string",
},
Create a FHIR Resource
Description

Can be used to create a FHIR resource with a given type.

See also:

Path
POST /fhir/{fhirVersion}/{resourceType}
Headers

This endpoint receives authentication in the form of a http bearer authentication header.

For example, Authorization: Bearer <user_access_token_here>.

Responses
http status code: 200
A FHIR Resource containing all the attributes that were posted.
application/json
{
  
  // additional attributes will be present depending on the resource posted
  "id" : "string",
  "resourceType" : "string",
},
Get all user data
Description

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.

Path
GET /fhir/{fhirVersion}/Patient/{patientId}/$everything
Headers

This endpoint receives authentication in the form of a http bearer authentication header.

For example, Authorization: Bearer <user_access_token_here>.

Responses
http status code: 200
A FHIR Bundle containing all the resources that match the query
application/json
{
  // 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" :   [
  ],
},
Grant permissions to user
Description

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.

Path
PUT /fhir/dstu2/Patient/patientid/_permission/{oneUpUserId}
Responses
http status code: 200
application/json
{
  
  // would be non-empty if an error occurred during the request
  "error" : "string",
},
Revoke permissions from user
Description

This endpoint allows you to remove permissions that have been granted to users to see other users' FHIR resources.

Path
DELETE /fhir/dstu2/Patient/patientid/_permission/{oneUpUserId}
Responses
http status code: 200
application/json
{
  
  // would be non-empty if an error occurred during the request
  "error" : "string",
},
Health System Picker UI
Description

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.

Path
GET /connect
Responses
http status code: 200
text/html
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.
Get Supported Health Systems
Description

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.

Path
GET /connect/system/clinical
Responses
http status code: 200
Returns an array of object containing information about health systems.
application/json
[
  {
    "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
Description

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 invidually requested to retrieve the data.

Path
GET /bulk-data/{fhirVersion}/$export
Query Parameters
_type — string

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.

For example, Authorization: Bearer <user_access_token_here>.

Responses
http status code: 200
application/json
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",
    },
  ],
},