Quick Guide for Developers

Developer Documentation

1upHealth provides a common RESTful API across 300 hospital systems (our network) with more added each month. This API fully supports FHIR and provides rich programmatic access to electronic medical record data for patients and the companies and institutions who serve them. The available data includes patient demographics, labs, medications, observations, procedures, allergies, and much more.

The 1upHealth platform is HIPAA compliant and in use by some of the largest hospital systems. You can get started for free with our developer tier.

Register

Register as a 1upHealth developer by clicking on "Get API Keys". This link can be found on top right corner, throughout our website.

Go to Sign up page

After clicking on "Get API keys" link, you will be taken to a login page where you can either login or sign up.

Fill the sign up form

Provide us with your email, username, and a strong password, then simply click on sign up button at the end.

Confirm your email

Confirm the email address that you provided by clicking on the link in the email sent to you by 1upHealth.

Login into your account

You can go to the login page by clicking on the "Get API Keys". After logging in, you will be taken to your dashboard. Now click on "ADD YOUR FIRST APPLICATION".

Create application

Now enter name of your application and OAuth2 redirect URL (root url of your application) then click on "SAVE".

Save application details

Now you will be shown your application details. Make sure you save your clientid and secret (keep it safe and secure, you won’t be able to see it again).

Use the User API

For each user, the 'code' variable is the OAuth2 access code. You will exchange the 'code' to get the OAuth2 access token. The access_token and refresh_token will be used to gain access to the user's data. Keep secure.

If you need to generate a new ‘code’ for a user that you created previously:


{
    curl -X POST "https://api.1up.health/user-management/v1/user"  

    -d "app_user_id=myappsuserid"  

    -d "client_id=clientidclientidclientid"  

    -d "client_secret=clientsecretclientsecret"
}

Here is the user flow (OAuth2).

1) Created new user (akuafo100), receive user code. If needed, generate a new code.


Response:
{
    "success": true,/n
    "code": "75b74e18e1504fde865f40f4308317b2",

    "oneup_user_id": 62198,

    "app_user_id": "akuafo100",

    "active": true
}

2) Exchange user code for bearer token (and refresh token).


Response:
{
    "refresh_token": "976ce65c6c8446d481eac6864389daa1", 

    "token_type": "bearer",

    "access_token": "595877199ebc4f3e86d208075dc521c6",

    "expires_in": 7200

}

3) Create FHIR resources and associate with the user, using the user's token. For example, create a Patient resource, and give the user a name, gender, and age. You get to define your own ID value for the resource.


Response:
{
    "resourceType": "Patient",
    "id": "96877a4ff0c6",
    "meta": {
        "versionId": "9000000000002",
        "lastUpdated": "2019-03-19T21:10:19.727Z"
    },
    "name": [
        {
            "use": "official",
            "family": [
                "Osler"
            ],
            "given": [
                "William"
            ]
        }
    ],
    "gender": "male",
    "birthDate": "1919-01-01"
}

4) Query the user resource for Patient that you just created by using its ID and the user token. You’ll only see basic data with this endpoint. Once you add a health system EHR or device, you’ll query other endpoints to get more data.


https://api.1up.health/fhir/dstu2/Patient/96877a4ff0c6
                                    

Response:
{
    "birthDate": "1919-01-01",
    "meta": {
        "lastUpdated": "2019-03-19T21:10:19.727Z",
        "versionId": "9000000000002"
    },
    "name": [
        {
            "family": [
                "Osler"
            ],
            "given": [
                "William"
            ],
            "use": "official"
        }
    ],
    "gender": "male",
    "resourceType": "Patient",
    "id": "96877a4ff0c6"
}

Use the EHR API to connect (which is the same as the device API)

1) Send the user to the website to login

Modify this URL:


https://api.1up.health/connect/system/{clinical || device}/healthsystemordeviceid?client_id=clientidclientidclientid&access_token=accesstokenaccesstoken

In the URL:

  • Choose either 'clinical' or 'device' as appropriate for the network you're accessing
  • The client_id is the app's client id
  • The access_token is the user's access token that's used in other API calls in the header after 'Bearer '

For example, to add data from an Epic EHR to the user's account, you can use this URL:


https://api.1up.health/connect/system/clinical/4706?client_id=b55413ca61bf42d6878cedaa348a5ea9&access_token=595877199ebc4f3e86d208075dc521c6

Then, login into EPIC with sample credentials (fhirjason / epicepic1):

After authenticating, the browser if first redirected to 1uphealth. 1upHealth will be given an access token for that user. 1upHealth will begin collecting data from that provider or device.

Then, the browser is redirected to the URL you provided as the app's URL [you do not need to retrieve any variables, 1up has already collected them]

Access data from the user

Data will automatically flow into 1upHealth and will be synchronized within a 2 minute time frame.

EHR (clinical data) will be stored as their native FHIR resources.

Device data will be stored as an Observation resource.

You can now retrieve data. In each request, you must include the user’s access token as an API header.

For example, retrieve patient demographics:


GET https://api.1up.health/fhir/dstu2/Patient