Introduction

This series of examples shows how to do many common activities with the onpatient API. For more detailed information, view the documentation.

Create an account

You need an onpatient account which is associated with at least one provider in order to create and test your application. Sign up!

Create your application

To create your application, go to the settings page (also available under "User" > "Settings" > "FHIR API Application") and click the "Edit" button. Fill in the name of your application and add one or more Redirect URIs, then click the "Save Changes" button on the bottom.

A Redirect URI is a web location starting with http:// or https:// that the user will be redirected to during the log-in flow. Note that this must be an address you control, but it need not present any content to the user, although we do recommend presenting a helpful message such as "Congratulations! You just integrated with :app!".

Client setup

For performing the OAuth workflow, you can use an OAuth 2.0 library. This page lists clients for various popular programming languages. You can find your client id, secret, and redirect URIs for configuring your library on the settings page, and the authorization and token URLs are:

  • Authorize URL: https://onpatient.com/o/authorize/
  • Access Token URL: https://onpatient.com/o/token/

You can also perform the OAuth workflow using any general purpose HTTP client library.

OAuth

Our API uses OAuth 2.0, a common web-based authorization system. It provides a straightforward way for a provider to grant access your application access to their data.

Authentication workflow

There are three main steps in the OAuth 2.0 authentication workflow:

  1. Redirect the provider to the authorization page.
  2. The provider authorizes your application and is redirected back to your web application.
  3. Your application exchanges the authorization_code that came with the redirect for an access_token and refresh_token.

Step 1: Redirect to onpatient

The first step is redirecting your user to onpatient, typically with a button labeled "Connect to onpatient" or "Login with onpatient". This is just a link that takes your user to the following URL:

https://onpatient.com/o/authorize/?redirect_uri=REDIRECT_URI_ENCODED&response_type=code&client_id=CLIENT_ID_ENCODED&scope=SCOPES_ENCODED
  • REDIRECT_URI_ENCODED is the URL-encoded version of the redirect URI (as registered for your application and used in later steps).
  • CLIENT_ID_ENCODED is the URL-encoded version of your application's client ID.
  • SCOPES_ENCODED is a URL-encoded version of a space-separated list of scopes, which can be found in the documentation or omitted to default to all scopes.

Step 2: Provider authorization

After logging in (if necessary), the provider will be presented with a screen with your application's name and the list of permissions you requested (via the scope parameter).

When they click the "Authorize" button, they will be redirected to your redirect URI with a code query parameter appended, which contains an authorization code to be used in step 3. If they click the "Cancel" button, they will be redirected to your redirect URI with error=access_denied instead.

Note: This authorization code expires extremely quickly, so you must perform step 3 immediately, ideally before rendering the resulting page for the end user.

Step 3: Token exchange

The code obtained from step 2 is usable exactly once to obtain an access token and refresh token. Here is an example token exchange in Python:

import datetime, pytz, requests

if 'error' in get_params:
    raise ValueError('Error authorizing application: %s' % get_params[error])

response = requests.post('https://onpatient.com/o/token/', data={
    'code': get_params['code'],
    'grant_type': 'authorization_code',
    'redirect_uri': 'http://mytestapp.com/redirect_uri',
    'client_id': 'abcdefg12345',
    'client_secret': 'abcdefg12345',
})
response.raise_for_status()
data = response.json()

# Save these in your database associated with the user
access_token = data['access_token']
refresh_token = data['refresh_token']
expires_timestamp = datetime.datetime.now(pytz.utc) + datetime.timedelta(seconds=data['expires_in'])

You now have all you need to make API requests authenticated as that provider. When using this access token, you'll only be able to access the data that the user has access to and that you have been granted permissions for.

Refreshing an access token

Access tokens only last 48 hours (given in seconds in the 'expires_in' key in the token exchange step above), so they occasionally need to be refreshed. It would be inconvenient to ask the user to re-authorize every time, so instead you can use the refresh token like the original authorization to obtain a new access token. Replace the code parameter with refresh_token, change the value grant_type from authorization_code to refresh_token, and omit the redirect_uri parameter.

Example in Python:

...
response = requests.post('https://onpatient.com/o/token/', data={
    'refresh_token': get_refresh_token(),
    'grant_type': 'refresh_token',
    'client_id': 'abcdefg12345',
    'client_secret': 'abcdefg12345',
})
...

Main API Usage

Main API is made to different URL https://drchrono.com than authorizing.

Getting user demographics

The /onpatient_api/fhir/Patient, is one of the endpoints that support retrieve object by id.

import requests

headers = {
    'Authorization': 'Bearer ACCESS_TOKEN',
}

url = 'https://drchrono.com/onpatient_api/fhir/Patient/PATIENT_ID'
response = requests.get(url, headers=headers)
response.raise_for_status()
data = response.json()

Getting patient immunization information

The /onpatient_api/fhir/Immunization/, like all listing endpoints, is paginated. You'll need to iterate over the results to get them all.

import requests

headers = {
    'Authorization': 'Bearer ACCESS_TOKEN',
}

patients = []
patients_url = 'https://drchrono.com/onpatient_api/fhir/Immunization'
while patients_url:
    data = requests.get(patients_url, headers=headers).json()
    patients.extend(data['results'])
    patients_url = data['next'] # A JSON null on the last page

Result contains all immunization objects that the request user has access to, and also all immunization objects follow FHIR Immunization