1upHealth Docs
1upHealth Docs
1up Homepage
Support
DevConsole
Get API Keys
Introduction
Getting Started
Quick Start Guide
FHIR Test Credentials
Production Access
NodeJS Demo App
Intro To FHIR
FAQ's
SMART On FHIR® App Connection
APIs
REST API Reference
Auth
User Management
Connect (Patient)
Connect (Direct EHR)
FHIR
Analytics
Provider Search
Open Data
Apple Health REST API
Blockchain FHIR Provenance
Architecture
Overview
Security
What's New
External Resources

REST API Reference

get
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
Request
Response
Request
Headers
Authorization
required
string
This endpoint receives authentication in the form of a http bearer authentication header.
Response
200: OK
User successfully retrieved.
{
  "oneup_user_id" : "string",
  "app_user_id" : "string",
  
  // Indicates whether the user is active or not
  "active" : "boolean",
},
400: Bad Request
Could not find a user matching this query.
{
  // would be non-empty if an error occurred during the request
  "error" : "string",
},

​

post
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.
Request
Response
Request
Headers
Authorization
optional
string
This endpoint receives authentication in the form of a http bearer authentication header.
Form Data Parameters
app_id_user
required
string
Self defined username.
secret
required
string
1/2 API keys generated in creating a new app.
client_id
required
string
1/2 API keys generated in creating a new app.
Response
200: OK
User successfully retrieved.
{
  "success" : "boolean",
  "code" : "string",
  "app_user_id" : "string",
  "oneup_user_id" : "string",
  "active" : "boolean",
}
404: Not Found
Could not find a user matching this query.
{
  // would be non-empty if an error occurred during the request
  "error" : "string",
}

put
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.
Request
Response
Request
Form Data Parameters
app_user_id
required
string
Self defined username.
client_id
required
string
1/2 API keys generated in creating a new app.
secret
required
string
1/2 API keys generated in creating a new app.
Response
200: OK
User successfully updated.
{
   "oneUpUserId" : 123456789,
   "success" : true
}

post
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).
Request
Response
Request
Form Data Parameters
app_user_id
required
string
Self defined username.
client_id
required
string
1/2 API keys generated in creating a new app.
secret
required
string
1/2 API keys generated in creating a new app.
Response
200: OK
{
  "client_id" : "string",
  "app_user_id" : "string",
  "client_secret" : "string",
}
404: Not Found
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",
}

post
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.
Request
Response
Request
Form Data Parameters
code
required
string
Access code is exchanged for the bearer token.
grant_type
required
string
Self defined username.
client_id
required
string
1/2 API keys generated in creating a new app.
secret
required
string
1/2 API keys generated in creating a new app.
Response
200: OK
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
Get FHIR® Resources

https://api.1up.health/fhir/{fhirVersion}/{resourceType}
Returns all matching FHIR
Request
Response
Request
Query Parameters
_content
optional
string
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
_count
optional
number
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
Response
200: OK
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" :   [
  ],
}

​

post
Create a FHIR® Resource

https://api.1up.health/fhir/{fhirVersion}/{resourceType}
Can be used to create a FHIR® resource with a given type.
Request
Response
Request
Headers
Authorization
required
string
This endpoint receives authentication in the form of a http bearer authentication header.
Response
200: OK
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
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.
Request
Response
Request
Headers
Authorization
required
string
This endpoint receives authentication in the form of a http bearer authentication header.
Response
200: OK
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
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.
Request
Response
Request
Headers
Authorization
required
string
This endpoint receives authentication in the form of a http bearer authentication header.
Response
200: OK
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" :   [
  ],
}

put
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.
Request
Response
Request
Form Data Parameters
client_secret
required
string
1 of 2 API keys generated in creating a new app.
client_id
required
string
1 of 2 API keys generated in created a new app.
oneup_user_id
required
number
System generated id.
Response
200: OK
User updated.
{
   "oneUpUserId" : 12345,
   "success" : true
}

delete
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.
Request
Response
Request
Headers
Authorization
required
string
This endpoint receives authentication in the form of a http bearer authentication header.
Response
200: OK
Delete User Permissions.
{
   "oneUpUserId" : 12345,
   "success" : true
}

get
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.
Request
Response
Request
​
Response
200: OK
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
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.
Request
Response
Request
Headers
Authorization
required
string
This endpoint receives authentication in the form of a http bearer authentication header.
Response
200: OK
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
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.
Request
Response
Request
Query Parameters
health_systems_only
optional
string
Enter `true` as the value.
query
optional
string
Enter name of the health system.
Response
200: OK
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" :     [
    ],
  },
]

get
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.
Request
Response
Request
Path Parameters
_type
optional
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
Authorization
optional
string
This endpoint receives authentication in the form of a http bearer authentication header.
Response
200: OK
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",
    },
  ],
}
Getting Started - Previous
SMART On FHIR® App Connection
Next - APIs
Auth
Last updated 3 days ago
Contents
get
Get Users
post
Create User
put
Update User
post
Generate User Authorization Code
post
Generate Access Token
get
Get FHIR® Resources
post
Create a FHIR® Resource
get
Get All User Data
delete
Delete All User Data
put
Grant Permission to User
delete
Revoke Permissions From User
get
Health System UI
get
Search Health Systems
get
Get Supported Health Systems
get
Bulk Data Export