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 (DSTU2) (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. Both kind of requests must be made using onpatient URL https://onpatient.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+fhir, 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, will follow FHIR bundle and has the following format:

{
    "resourceType": "Bundle"',
    "type": "searchset",
    "total": integer,                 // total number of objects returned
    "link": list of link objects,     // links related to bundle
    "entry": list 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

Basic 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"

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 Yes See here for a detailed explanation.
response_type string Yes Use code

/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)
token_type string It is always Bearer
scope string Space separated scopes authorized for the corresponding token

/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: API requests should be made using onpatient URL https://onpatient.com.

Endpoints

/api/fhir/AllergyIntolerance

This endpoint contains information about a record of a clinical assessment of an allergy or intolerance. For more information, please see FHIR AllergyIntolerance

Required scopes: patient/*.read

Supported requests: GET

Filtering parameters:

Key Type Description
patient integer Only retrieve objects of the given patient
_lastUpdated timestamp Only retrieve objects updated after the given timestamp

Object key/values:

Key Type Always present Notes
id integer Yes
patient FHIR Reference Yes Reference to patient
substance FHIR CodeableConcept Yes Substance considered to be responsible for risk
status FHIR code Yes Allergy status. One of active or inactive

/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

Filtering parameters:

Key Type Description
patient integer Only retrieve objects of the given patient
_lastUpdated timestamp Only retrieve objects updated after the given timestamp

Object key/values:

Key Type Always present Notes
id integer Yes
patient FHIR Reference Yes Reference to patient
code FHIR CodeableConcept Yes Identification of the condition, problem or diagnosis
clinicalStatus FHIR code Yes Clinical status value set FHIR Condition clinical status
onsetDateTime FHIR dateTime Yes Onset datetime on record.

/api/fhir/DiagnosticReport

This endpoint contains information about findings and interpretation of diagnostic tests performed on patients

Required scopes: patient/*.read

Supported requests: GET

Filtering parameters:

Key Type Description
patient integer Only retrieve objects of the given patient
_lastUpdated timestamp Only retrieve objects updated after the given timestamp

Object key/values:

Key Type Always present Notes
id integer Yes
code FHIR CodeableConcept Yes Name/Code for this diagnostic report
status FHIR code Yes diagnostic report status value set
subject FHIR Reference Yes
effectiveDateTime FHIR dateTime Clinically Relevant time/time-period for report
issued FHIR instant Yes DateTime this version was released
performer FHIR Reference Yes Responsible Diagnostic Service
result FHIR Reference Yes Observations - simple, or complex nested groups

/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

Filtering parameters:

Key Type Description
patient integer Only retrieve objects of the given patient
_lastUpdated timestamp Only retrieve objects updated after the given timestamp

Object key/values:

Key Type Always present Notes
id integer Yes
patient FHIR Reference Yes Reference to patient
status FHIR code Yes Status of medication administration. Immunization Status value set
date FHIR dateTime Yes Vaccination administration date
vaccineCode FHIR CodeableConcept Yes Vaccine product administered
wasNotGiven boolean Yes Flag for whether immunization was given
reported boolean Yes Indicates a self reported record

/api/fhir/Medication

This resource is primarily used for the identification and definition of a medication. It covers the ingredients and the packaging for a medication.

Required scopes: patient/*.read

Supported requests: GET

Filtering parameters:

Key Type Description
code string Only retrieve objects related with given RxNorm code

Object key/values:

Key Type Always present Notes
id integer Yes
code FHIR CodeableConcept Yes

/api/fhir/MedicationOrder

An order for both supply of the medication and the instructions for administration of the medication to a patient.

Required scopes: patient/*.read

Supported requests: GET

Filtering parameters:

Key Type Description
patient integer Only retrieve objects of the given patient
_lastUpdated timestamp Only retrieve objects updated after the given timestamp

Object key/values:

Key Type Always present Notes
id integer Yes
dateWritten FHIR dateTime Yes When prescription was authorized
patient FHIR Reference Yes
medicationCodeableConcept FHIR CodeableConcept Yes Medication to be taken
note string Yes Information about the prescription

/api/fhir/MedicationStatement

A record of a medication that is being consumed by a patient.

Required scoeps: patient/*.read

Supported requests: GET

Filtering parameters: Key | Type | Description ----|------|------------ patient | integer | Only retrieve objects of the given patient _lastUpdated | timestamp | Only retrieve objects updated after the given timestamp

Object key/values:

Key Type Always present Notes
id integer Yes
medicationCodeableConcept FHIR CodeableConcept Yes What medication was taken
patient FHIR Reference Yes
status FHIR code Yes Medication statement status value set

/api/fhir/Observation

Measurements and simple assertions made about a patient, device or other subject. For more information, please see FHIR Observation

Required scopes: patient/*.read

Supported requests: GET

Filtering parameters:

Key Type Description
patient integer Only retrieve observation of the given patient
_lastUpdated timestamp Only retrieve objects updated after the given timestamp

Object key/values:

Key Type Always present Notes
id string Yes
status FHIR code Yes Observation status value set
category FHIR CodeableConcept Yes Observation category value set
code FHIR CodeableConcept Yes Type of observation
subject FHIR Reference Yes
effectiveDateTime FHIR dateTime Yes Clinically relevant time for observation
referenceRange See here for more details No Most of the time, this field will exist when the object's category is laboratory
interpretation FHIR CodeableConcept No Most of the time, this field will exist when the object's category is laboratory and its result is numerical value.
valueString string No This field will exist when the object's result value is non-numerical
valueQuantity FHIR Quantity No This field will exist when the object's result value is numerical
dataAbsentReason FHIR CodeableConcept No This field will exist when the object's result is missing

/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

Filtering parameters:

Key Type Description
_id integer Only retrieve object with the given patient id
_lastUpdated timestamp Only retrieve objects updated after the given timestamp

Object key/values:

Key Type Always present Notes
id integer Yes Unique identifier for patient
birthDate date Yes The date of birth of the individual
gender FHIR code Yes Patient gender value set
name FHIR HumanName Yes A name associated with the patient

/api/fhir/Procedure

An action that is or was performed on a patient.

Required scopes: patient/*.read

Supported requests: GET

Filtering parameters:

Key Type Description
patient integer Only retrieve observation of the given patient
_lastUpdated timestamp Only retrieve objects updated after the given timestamp

Object key/values:

Key Type Always present Notes
id integer Yes
status FHIR code Yes Procedure status value set
subject FHIR Reference Yes
code FHIR CodeableConcept Yes Identification of the procedure
performedDateTime FHIR dateTime Yes Date the procedure was performed