REST API Reference

To view our interactive, Open API Swagger definition, please visit:
​Swagger​
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 from code
https://auth.1up.health/oauth2/token
A back-end 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
authorization_code
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",
}
post
Generate Access Token from Refresh Token
https://auth.1up.health/oauth2/token
A back-end app can use this endpoint to exchange the refresh_token for a user for an access_token, refresh_token and id_token.
Request
Response
Request
Form Data Parameters
client_id
required
string
API key generated for your app
client_secret
required
string
API key generated for your app
refresh_token
required
string
refresh token
grant_type
required
string
"refresh_token"
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/{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., /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., /dstu2/Patient?_count=10
_skip
optional
number
The _skip query parameter enables users to specify which resource in the response bundle to start at i.e. how many resources in the response bundle to skip. For example /r4/Patient?_skip=10 would skip the first 10 resources, and response would start on the 11th resource.
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/{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/{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/{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/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/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
​
https://api.1up.health/connect
Request
Response
Request
Path Parameters
optional
string
​
Response
200: OK
​
get
​
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",
    },
  ],
}
get
FHIR R4 _include
https://api.1up.health/r4/{resourceType}?_include={resourceType}:{referencedResourceType}
For FHIR R4 APIs only, the ability to include referenced resources in your search query. For example /r4/MedicationRequest?_include=MedicationRequest:patient returns the Patient resources referenced by the MedicationRequest resource.
Request
Response
Request
Path Parameters
_include
optional
string
Path param to specify you want to include referenced resources. Can be FHIR resource type OR can be '*' to include all referenced resources
Response
200: OK
​
get
FHIR R4 _revinclude
https://api.1up.health/r4/{resourceType}?_revinclude={resourceType}:{referencedResourceType}
For FHIR R4 APIs only, the ability to fetch a particular resource, and any resources that refer to it. For example, the client may wish to fetch a MedicationRequest, and any provenance resources that refer to the prescription. This is known as a reverse include, and is specified by providing a _revinclude parameter.
Request
Response
Request
Path Parameters
optional
string
Specifies you want to include resources to refer back to the resource you are querying for. Can be specific FHIR resource type OR '*'
Response
200: OK
​
Health Plan Directory
Next - APIs
Auth
Last updated 2 months ago
REST API Reference

getGet Users

postCreate User

putUpdate User

postGenerate User Authorization Code

postGenerate Access Token from code

postGenerate Access Token from Refresh Token

getGet FHIR® Resources

postCreate a FHIR® Resource

getGet All User Data

deleteDelete All User Data

putGrant Permission to User

deleteRevoke Permissions From User

get​

get​

getGet Supported Health Systems

getBulk Data Export

getFHIR R4 _include

getFHIR R4 _revinclude

get
Get Users

post
Create User

put
Update User

post
Generate User Authorization Code

post
Generate Access Token from code

post
Generate Access Token from Refresh 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

get

get
Get Supported Health Systems

get
Bulk Data Export

get
FHIR R4 _include

get
FHIR R4 _revinclude
