Table of Contents

Introduction

This documentation is intended as a detailed reference for the precise behaviour of {onpatient FHIR API}. This API is built based on FHIR (Fast Healthcare Interoperability Resources), which is a standard for exchanging healthcare information electronically. If this is your first time using the API, start with our tutorial.

Requests

There are two different kinds of requests, authentication requests and data query requests. Authentication requests must be made using onpatient URL https://onpatient.com, while data query requests must be made using drchrono URL https://drchrono.com.

We only support GET method for now, and we are actively working on exposing write access on each endpoint. Also please note, not all endpoints support retrieving by id.

Path Method Effects Success Status Failure Status Response Content
:endpoint GET None 200 403 Paginated list of all endpoint resources that the requester can access
:endpoint/:id GET None 200 403 or 404 Object with requested id

Requests should make sure not to send Accept: test/html in the header, as the API only supports JSON responses.

Responses

All responses are in JSON format. Generally input may use the application/json, application/x-www-form-urlencoded or form/multipart content types.

The list of objects returned by a GET request to :endpoint is paginated and has the following format:

{
    "count": integer,                       // total number of pages this response has
    "next": URL or null,                    // URL of the next page
    "previous": URL or null,                // URL of the previous page
    "results": array of result objects
}

The page size is default to 50, and can be changed by setting the page-size query parameter. Some endpoints may allow additional query parameters to filter the listed results.

Some endpoints may return a 302 redirect response. Most libraries handle this incorrectly by resending the response with different headers or a different HTTP method; you need to resend the original request with the right HTTP method and headers to the new Location specified by the 302 response.

Permissions

API access is managed using scopes and permissions. Scopes are granted to an API Application when a user authorizes. The scopes are granted during the OAuth process, whereas the permissions have to be granted from drchrono web app. In order for an app to access information on behalf of a drchrono user, the user must authorize the app for the required scopes, and the user must have the appropriate permissions set.

Documentation Structure

Each section consists of a list of endpoints, each of which is accompanied by the following data:

  • A brief description of the objects accessed through the endpoint,
  • The scopes required to access the endpoint,
  • The request types supported by the endpoint (GET),
  • Any query parameters which can be used to filter results,
  • A table of key-value pairs present in the JSON response from the endpoint.

Key-value pairs are presented as tables containing the key, the type of the object, and a description of its function if it is not obvious from context. Also the documentation will explicitly indicate whether a field is guaranteed to be present.

Data Types

The data types referred to in the documentation, for both requests and responses, are listed below.

Type Category Example
boolean Primitive true
integer Primitive 123
decimal Primitive 123.45
string Primitive "Hello, world!"
URL Primitive "http://example.com/index.html"
date Primitive "2017-05-31"
datetime Primitive "2017-05-31T12:34:56"
HumanName Complex
Address Complex
ContactPoint Complex
Coding Complex
CodeableConcept Complex
Quantity Complex
BackboneElement Complex

Rate Limits

Applications are subject to an hourly rate limit, which reset at the top of each hour. Requests over this limit will receive a response with status code 429. By default, applications are limited to 500 calls per hour. Contact sales@drchrono.com or your account representative to request an increased rate limit.

Stability Policy

Changes to this API version will be limited to adding endpoints, or adding fields to existing endpoints, or adding optional query parameters. Any new fields which are not read-only will be optional.

OAuth

These endpoints are used to obtain access tokens, which are necessary for all other API calls.

Note: OAuth requests should be made using onpatient URL https://onpatient.com. The POST OAuth endpoint URLs require the trailing slash. Also, they accept x-www-urlencoded parameters, not application/json.

Endpoints

/o/authorize

Unlike the other endpoints in this document, API applications do not contact /o/authorize directly. Instead, users of the application should be redirected to /o/authorize. The user will be prompted to authorize the application, they are redirected to redirect_uri with the query parameter code, which will be used by the application to query the /o/token endpoint. Note that the code parameter expires after 1 minute.

Allowed requests: GET

Request parameters:

Key Type Required Notes
client_id string Yes The Client ID identifying your application, which can be found on the API management page.
redirect_uri URL Yes The URL to which the user is redirected after authorizing your application. Must be one of the redirect URIs registered with your application on the API management page.
scope string No See here for a detailed explanation.

/o/token/

Allows applications to exchange the code parameter from the previous endpoint for access and refresh tokens.

Allowed requests: POST

Request parameters:

Key Type Required Notes
grant_type string Yes Either "authorization_code" or "refresh_token"
client_id string Yes The Client ID identifying your application, which can be found on the API management page.
client_secret string Yes Also on the API management page
redirect_uri string Yes The URL to which the user was redirected after granting authorization
code string No* (see note) Passed to the redirect URI when the user chooses to authorize an application. Required if grant_type is "authorization_code".
refresh_token string No* (see note) Used to refresh an expired authorization token. Required if grant_type is "refresh_token".

Response parameters:

Key Type Notes
access_token string Requests to the other endpoints must include the Authorization header with value Bearer :access_token
refresh_token string Used to get a new access and refresh token after the access token expires
expires_in integer Number of seconds until expiry, which is always 172800 (48 hours)

/o/revoke_token/

Allows applications to revoke an access token before it expires. This is useful for testing purposes.

Request parameters:

Key Type Required Notes
client_id string Yes The Client ID identifying your application, which can be found on the API management page
client_secret string Yes Also on the API management page
token string Yes The access token to revoke

Main API

These are the main endpoints which are accessible to every application.

Note: Main API requests should be made using drchrono URL https://drchrono.com.

Endpoints

/onpatient_api/fhir/Patient

This endpoint contains demographic information about individual receiving health care services. For more information, please see FHIR Patient.

Required scopes: patient/*.read

Supported requests: GET

Retrieve by id supported: Yes

Filtering parameters:

Key Type Description

This endpoint current does not support any filter parameters.

Object key/values:

Key Type Always present Notes
identifier integer Yes Unique identifier for patient
active boolean Yes Whether the patient's record is in active use
address Address Yes Address of the individual
birthDate date Yes The date of birth of the individual
gender string Yes One of "male", "female" or "other"
name HumanName Yes A name associated with the patient
teleCom ContactPoint Yes A contact detail for the patient

/onpatient_api/fhir/Observation

This endpoint contains information about measurements and simple assertions made about a patient. There are three different category of observations available, which are smoking status, lab results and vital signs. Different category has different response object keys. For more information, please see FHIR Observation

Required scopes: patient/*.read

Supported requests: GET

Retrieve by id supported: No

Filtering parameters:

Key Type Description
patient integer Only retrieve observation of the given patient
category string Only retrieve observation of the given category, value can be one of social-history, laboratory or vital-signs

Object key/values:

Key Type Always present Notes
subject integer Yes Unique identifier for the patient
category CodeableConcept Yes Classification of type of observation, value is bounded, can only be CodebleConcept of one of social-history, laboratory or vital-signs. FHIR Observation Category
status string Yes Status of the observation. FHIR Observation Status
code CodeableConcept Yes Type of observation. FHIR Observation Code
issued datetime No If present, represents the date/time this was made available
effectiveDateTime datetime No If present, represents the datetime when vital sign is effective.
valueCodeableConcept CodeableConcept No If present, represents the actual results.
valueQuantity Quantity No If present, represents the actual results.
referenceRange BackboneElement No If present, provides guide for interpolation for lab results
component array of CodeableConcept No If present ,represents component result (blood pressure) for vital signs
dataAbsentReason CodeableConcept No If present, represents data absent reason for vital signs

/onpatient_api/fhir/Immunization

This endpoint contains information about the event of a patient being administered a vaccination or a record of a vaccination as reported by a patient, a clinician or another party. For more information, please see FHIR Immunization

Required scopes: patient/*.read

Supported requests: GET

Retrieve by id supported: No

Filtering parameters:

Key Type Description
patient integer Only retrieve observation of the given patient

Object key/values:

Key Type Always present Notes
patient integer Yes Unique identifier for patient
status string Yes Status of medication administration. FHIR Immunization Status
date datetime Yes Vaccination administration date
vaccineCode CodeableConcept Yes Vaccine product administered
wasNotGiven boolean Yes Flag for whether immunization was given
reported boolean Yes Indicates a self reported record

/onpatient_api/fhir/Condition

This endpoint contains information about conditions, problems and diagnoses recognized by a clinician. For more information, please see FHIR Condition

Required scopes: patient/*.read

Supported requests: GET

Retrieve by id supported: No

Filtering parameters:

Key Type Description
patient integer Only retrieve observation of the given patient

Object key/values:

Key Type Always present Notes
patient integer Yes Unique identifier for patient
category CodeableConcept Yes Condition category. FHIR Condition Category
code CodeableConcept Yes Identification of the condition.
clinicalStatus string Yes Clinical status FHIR Condition clinical status
onsetDateTime datetime Yes Onset datetime on record.

/onpatient_api/fhir/AllergyIntolerance

Required scopes: patient/*.read

Supported requests: GET

Retrieve by id supported: No

Filtering parameters:

Key Type Description
patient integer Only retrieve observation of the given patient

Object key/values:

Key Type Always present Notes
patient integer Yes Unique identifier for patient
status string Yes Allergy status. One of active or inactive