REST API Endpoint Reference

You can use the following 1upHealth FHIR REST API endpoints to interact with the data on the 1upHealth FHIR Server.

GET  https://api.1up.health/user-management/v1/user

Get the list of all the users that exist inside your 1up Developer Application.

You can filter by user.

Parameters

Header    
Authorization string This endpoint receives authentication requests as an HTTP authentication header with a Bearer token.

Responses

200 
{
  "oneup_user_id" : "string",
  "app_user_id" : "string",

  // Indicates whether the user is active or not
  "active" : "boolean",
},
400 
{
  // would be non-empty if an error occurred during the request
  "error" : "string",
},

POST   https://api.1up.health/user-management/v1/user

This request creates a user with the attributes that you specify in the request body.

If the user already exists in the 1up FHIR Server, the request won't fail, but you'll receive the following error.

this user already exists

Parameters

Header    
Authorization string This endpoint receives authentication requests as an HTTP authentication header with a Bearer token.
Body    
app_user_id string Self-defined user name.

client_id

string

One of two API keys generated for a new application.

client_secret

string

One of two API keys generated for a new application.

Responses

200 
{
  "success" : "boolean",
  "code" : "string",
  "app_user_id" : "string",
  "oneup_user_id" : "string",
  "active" : "boolean",
}
404 
{
  // would be non-empty if an error occurred during the request
  "error" : "string",
}

PUT   https://api.1up.health/user-management/v1/user

You can use the Update User API to modify an existing user object.

You can modify only the app_user_id. The oneup_user_id can’t be changed.

Parameters

Header    

client_id

string

API key generated for your application.

client_secret

string

API key generated for your application.
Body    
app_id_user string Self-defined username

oneup_user_id

string

System-generated user ID based on the username.

Responses

200 
{
   "oneUpUserId" : 123456789,
   "success" : true
}

POST   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).

Parameters

Body    
app_user_id string Self-defined user name.

client_id

string

One of two API keys generated for a new application.

client_secret

string

One of two API keys generated for a new application.

Responses

200 
{
  "client_id" : "string",
  "app_user_id" : "string",
  "client_secret" : "string",
}
404

Returns an authorization code that you can exchange for an access token and refresh token.

{
  "success" : "boolean",
  "code" : "string",
  "oneup_user_id" : "string",
  "app_user_id" : "string",
  "active" : "boolean",
}

POST  https://auth.1up.health/oauth2/token

A back-end app can use this endpoint to exchange the authorization code for these tokens: access_token, refresh_token, and id_token. The id_token is only returned if you include the openid scope when you request the code.

Don’t call this endpoint in a browser because it requires exposing your applications secret key to users.

Parameters

Body    
code string Access code is exchanged for the bearer token.

grant_type

string

authorization_code

client_id

string

1/2 API keys generated in creating a new application.

secret

string

1/2 API keys generated in creating a new application.

Responses

200

Returns an access_token, refresh_token, and optional id_token.

The access_token expires in two hours (7200 seconds). To get a new access_token, use the refresh_token or generate a new authorization code.

{
  "client_id" : "string",
  "app_user_id" : "string",
  "client_secret" : "string",
}

POSThttps://auth.1up.health/oauth2/token

A back-end application can use this endpoint to exchange the refresh_token for a user for an access_token, refresh_token, and id_token.

Parameters

Body    
refresh_token string The refresh token generated for your application.

grant_type

string

refresh_token

client_id

string

API key generated for your application.

client_secret

string

API key generated for your application.

Responses

200

Returns an access_token, refresh_token, and optional id_token.

The access_token expires in two hours (7200 seconds). To get a new access_token , use the refresh_token or generate a new authorization code. 

{
  "refresh_token" : "string",
  "token_type" : "string",
  "access_token" : "string",
  "expires_in" : "integer",
  "scope" : "string",
  "id_token" : "string",
}

GET  https://api.1up.health/<fhirVersion>/<resourceType>

Returns all matching FHIR® resources.

Parameters

Query    
_content string

The _content query parameter enables users to text search against the entire resource in the response bundle.

Example — /dstu2/Patient?_content=Atul+Gawande

_count

number

refresh_token

_skip

number

API key generated for your application.

Responses

200

A paginated FHIR® Bundle that contains all the resources that match the query.

The default is 10 resources per bundle. 

{
  // For information about how a FHIR® bundle is structured, 
  // see https://www.hl7.org/fhir/bundle.html.

  // 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   https://api.1up.health/<fhirVersion>/<resourceType>

Use to create a FHIR® resource of a specified type.

Parameters

Header    
Authorization string This endpoint receives authentication requests as an HTTP authentication header with a Bearer token.

Responses

200

A FHIR® Resource that contains all of the attributes that were posted. 

{

  // additional attributes will be present depending on the resource posted
  "id" : "string",
  "resourceType" : "string",
}

GET  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.

Parameters

Header    
Authorization string This endpoint receives authentication requests as an HTTP authentication header with a Bearer token.

Responses

200 
{
  // 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  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.

Parameters

Header    
Authorization string This endpoint receives authentication requests as an HTTP authentication header with a Bearer token.

Responses

200 
{
  // 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" :   [
  ],
}

GET  https://system-search.1up.health/api/search

You can use this endpoint to search for providers supported by 1upHealth. You can use the query Search parameter.

Parameters

Query    

query

string

String matches on name, address.line, or address.city.

offset

number

Offset indicates the starting point within the result set.

system_type

string

Indicates the type of system: HealthSystem, Payer2Payer, or PayerPatientAccess
Header    

Authorization

string

Authentication token to verify who is accessing the system.

Responses

200 
[
    {
        "id": 4894,
        "name": "Michigan Medicine",
        "address": "1500 E Medical Center Dr",
        "fhirVersion": "FHIR R4",
        "ehr": "epic",
        "resourceUrl": "https://mcproxyprd.med.umich.edu/FHIR-PRD/api/FHIR/DSTU2",
        "logo": "https://1uphealth-assets.s3-us-west-2.amazonaws.com/systems/michigan-medicine.png",
    }
]

GET  https://api.1up.health/connect/system/clinical

Use this endpoint to query the full list of supported health systems.

If you want to implement a full-text search of providers using the name, address, or clinician name fields, we recommend that you use the System Search endpoint.

Parameters

Query    
systemType string

Either HealthSystem or PayerPatientAccess

query

number

The name of the health system

Responses

200 
[
  {
    "id" : "number",
    "name" : "string",
    "status" : "string",
    "logo" : "string",
    // Location contains addresses and name of health system
    "locations" :     [
    ],
  },
]

 

POSThttps://api.1up.health/connect/system/clinical

Use this endpoint to query the full list of supported health systems.

If you want to implement a full-text search of providers using the name, address, or clinician name fields, we recommend that you use the System Search endpoint.

Parameters

Header    
Accept   application/json

Content-Type

 

application/x-www-form-urlencoded
Body    

client_id

string

1up application Client ID

client_secret

string

1up application Client Secret

systemType

 

The type of system

Examples — HealthSystem or PayerPatientAccess

Responses

200: OK 
{
    // Response
}

GET  https://analytics.1up.health/bulk-data/<fhirVersion>/$export

This endpoint is for the multi-tenant environment (MTE) version of Bulk Export. If your implementation is a single-tenant environment (STE), see the topics in Bulk Data Export (Single Tenant).

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.

This request relies on retrieving an Access Token using the Auth Reference APIs (first get an authorization code, then exchange for an access token for a 1up user).

Parameters

Path    
_type string

Include to specify which types of FHIR® resources to export. To specify more than one resource type, include the resource types as a comma-separated list.

Example — 'Patient,Observation'

If your request includes an invalid resource type, your request will fail.
Header    
Authorization string This endpoint receives authentication requests as an HTTP authentication header with a Bearer token.

Responses

200

The returned list includes at least one download file for each resource type with data.

{

  // 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  https://analytics.1up.health/bulk-data/<fhirVersion>/$export

This endpoint is for the multi-tenant environment (MTE) version of Bulk Export. If your implementation is a single-tenant environment (STE), see the topics in Bulk Data Export (Single Tenant).

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.

This relies on using your client ID and client secret in the header of your request.

Parameters

Path    
_type string Optionally restrict the types of FHIR® resources to export with a comma-separated list of standard FHIR® resource types (such as 'Patient,Observation'). Note the request will fail if an invalid resource type is requested.
Header    
x-oneup-user-id string Either set to client to get all data across all users for client ID or to a specific 1up user ID (integer value) that you get from the User Management API.

client_secret

string

Your client secret for the data you want to get.

client_id

string

Your client ID for the data you want to get.

Responses

200

 

GET  https://gateway.1up.health/v1/<customer-URL>/bulk-export/bulk-data/r4/$export

Use this endpoint to export bulk data at the population level 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 population-level data.

This request relies on retrieving an Access Token using the Auth Reference APIs (first get an authorization code, then exchange for an access token for a 1up user).

Parameters

Path    
_type string

Include to specify which types of FHIR® resources to export. To specify more than one resource type, include the resource types as a comma-separated list.

Example — 'Patient,Observation'

If your request includes an invalid resource type, your request will fail.

_since

string

Resources are included in the response if their state has changed after the specified date.

Example: Resource.meta.lastUpdated is later than the specified _since value
Header    
Authorization string This endpoint receives authentication requests as an HTTP authentication header with a Bearer token.

Responses

200

The returned list includes at least one download file for each resource type with data.

{

  // 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  https://gateway.1up.health/v1/<customer-name>/bulk-export/bulk-data/r4/Group/<ID>/$export

Use this endpoint to export bulk data at the population level for a group using the FHIR® $export operator. This initial request returns a list of download files, which can be individually requested to retrieve the population-level data for the group.

This request relies on retrieving an Access Token using the Auth Reference APIs (first get an authorization code, then exchange for an access token for a 1up user).

Parameters

Path    
_type string

Include to specify which types of FHIR® resources to export. To specify more than one resource type, include the resource types as a comma-separated list.

Example — 'Patient,Observation'

If your request includes an invalid resource type, your request will fail.

_since

string

Resources are included in the response if their state has changed after the specified date.

Example: Resource.meta.lastUpdated is later than the specified _since value
Header    
Authorization string This endpoint receives authentication requests as an HTTP authentication header with a Bearer token.

Responses

200

The returned list includes at least one download file for each resource type with data.

{

  // 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  https://api.1up.health/r4/<resourceType>?_include=<resourceType>:<referencedResourceType>

For FHIR R4 APIs only, the ability to include referenced resources in your search query.

Example — /r4/MedicationRequest?_include=MedicationRequest:patient returns the Patient resources referenced by the MedicationRequest resource.

Parameters

Path    
_include string

Path parameter to include referenced resources.

This can be a FHIR resource type or you can specify '*' to include all referenced resources.

Responses

200

 

GEThttps://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.

Parameters

Path    
  string

Specifies that you want to include resources to refer to the resource you are querying.

This can be a FHIR resource type or you can specify '*' to include all referenced resources.

Responses

200