Table of Contents

Introduction

This document is intended as a detailed reference for the precise behavior of the drchrono v2016_06 API. If this is your first time using the API, start with our tutorial. If you are upgrading from a previous version, take a look at the changelog.

Requests

All requests must be made using the base URL https://drchrono.com.

For each endpoint, up to six different kinds of requests may be permitted:

Path Method Side Effects Success Status Failure Status Response Content
:endpoint GET None 200 403 Paginated list of all endpoint resources that the requester can access (data returned may be several seconds old)
:endpoint/:id GET None 200 403 or 404 Object with requested id
:endpoint POST Create object 201 400, 403 or 409 Object(s) created
:endpoint/:id PUT Update entire object 204 400, 403 or 409 Empty
:endpoint/:id PATCH Update only included values 204 400, 403 or 409 Empty
:endpoint/:id DELETE Delete object 204 400 or 403 Empty

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

There are several pitfalls with content-types:
  • The examples in this document generally assume the application/json content type. For other content types, omit quotation marks around strings.
  • Creating or updating nested objects, as well as creating multiple objects, are only supported using the application/json content-type.
  • Files are only supported using the form/multipart content-type.

When making a POST request to an endpoint, you may pass a list of objects (encoded as application/json) instead of a single object. This will create all objects in the list, and return a list of the resulting objects. The format for each object is the same as a normal POST request.

Some endpoints may return a 302 redirect response.

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:

{
  "next": URL or null,                  // URL of the next page (same as the requested URL, but with the page query parameter incremented)
  "previous": URL or null,              // URL of the previous page
  "results": array of result objects    // the results follow the same format as `:endpoint/:id`
}

The page size defaults to 250, but can be lowered 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 and permissions are granted by a primary user to other users in his or her Practice Group. 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:

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.

If the endpoint supports writing, each table will also indicate which the keys are required, optional or read-only. If a value is optional, it will either have a default noted in the table or it will default to "" or null depending on its type. These cases should be interpreted as an absent value. Unless otherwise noted, optional or read-only parameters with no default value may be null or "" in the response to a query, with the exception of the id field, which is always read-only but always present.

For endpoints that do not support either POST or PUT, 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 Example Description
boolean true
integer 123
string "Hello, world!"
URL "http://example.com/index.html" An absolute URL, including protocol
object {"key": "value"} A nested object. When a value is of type "object", the word "object" will always link to a popup with the object's format.
array [1, 2] A value may have type "array of :type"
date "2014-02-24" An ISO 8601 encoded date
date range "2014-02-24/2014-02-28" A start and end date separated by a slash
file "https://rackcdn.com/file.ext" When uploading, this is provided as a standard multipart/form-data file
base64encoded file "https://rackcdn.com/file.ext" When uploading, this is provided as a base64 encoded file within JSON
time "12:34:56" An ISO 8601 encoded time
timestamp "2014-02-24T15:32:19" An ISO 8601 encoded timestamp, with no timezone
color "#ABCDEF" or "rgb(12, 34, 45)" A CSS color specified in either of these formats
decimal "123.45" A numeric value truncated to two decimal places. It may be passed to an endpoint as an integer, float or string, but will always be returned as a string.

Verbose Parameter

For some endpoints, certain fields will be excluded in the response to a GET request unless the verbose query parameter is passed with the value true. These fields have a particularly large performance penalty. Passing verbose=true will include these keys in the response, but will reduce the default and maximum page sizes to 50.

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.

Deprecation Policy

The drchrono API is versioned. This document concerns version v2016_06, which can be changed using the dropdown in the upper right corner. Versions can be in the following states:

OAuth

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

Note: 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.

Endpoints

/api/appointments

Create, modify, retrieve and delete appointments and breaks on a doctor's calendar. Creating an appointment which overlaps with an existing one will fail with status code 409.

Note: when making a GET request to /api/appointments (not /api/appointments/:id), either the since, date or date_range query parameter must be specified.

Required scopes: calendar, clinical

Required permissions: Access Billing, Show Billing Tab, Access Clinical Notes

Practice group access: If the "share patients" setting is on

Supported requests: GET, POST, PUT, PATCH, DELETE

Keys requiring verbose=true: clinical_note, custom_vitals, vitals, reminders, extended_updated_at

Filtering parameters:

Key Type Description
date date Only retrieve appointments that occur on the given date
date_range date range Retrieve appointments in a time period (inclusive). Cannot be longer than 190 days, unless it is in the past.
doctor integer Only retrieve appointments for the doctor with the given ID
office integer Only retrieve appointments for the office with the given ID
patient integer Only retrieve appointments for the patient with the given ID
since timestamp Only retrieve appointments that have been updated since a given date
show_archived boolean If present when making a GET request without specifying an ID, archived results will be included. Not necessary when an ID is included in the URL.

Object key/values:

Key Type POST/PUT requests Notes
doctor integer required Doctor ID
duration integer required* (see note) Length of the appointment in minutes. Optional if profile is provided.
exam_room integer required Index of the exam room that this appointment occurs in. See /api/offices.
office integer required Office ID
patient integer or null required ID of this appointment's patient. Breaks have a null patient field.
scheduled_time timestamp required The starting time of the appointment
color string optional
custom_vitals array of objects optional Click on link for format. NOT the same as the object returned by /api/custom_vitals.
notes string optional
profile integer optional ID of an /api/appointment_profiles instance. The profile sets default values for color, duration and reason on creation, which can be overridden by setting these values explicitly.
reason string optional Default is ""
reminder_profile integer optional Write-only. ID of an /api/reminder_profiles instance. Set this to apply a reminder profile to the appointment. Cannot be applied to an appointment with reminders.
status string optional One of "", "Arrived", "Checked In", "In Room", "Cancelled", "Complete", "Confirmed", "In Session", "No Show", "Not Confirmed", or "Rescheduled"
vitals object optional Click on link for format
billing_status string optional Should be one of Auto Accident Claim, Balance Due, Bill Insurance, Bill Secondary Insurance, Durable Medical Equipment Claim, Internal Review, Paid In Full, Settled, Worker's Comp Claim or one of the custom billing status.
billing_provider integer read-only
clinical_note object read-only Click on link for format
icd10_codes string read-only
icd9_codes string read-only
id string read-only Unique identifier. Usually numeric, but not always.
reminders array of objects read-only Click on link for format
created_at timestamp read-only
updated_at timestamp read-only
first_billed_date timestamp read-only
last_billed_date timestamp read-only
deleted_flag boolean read-only Whether the appointment is deleted
primary_insurer_payer_id string read-only
primary_insurer_name string read-only
primary_insurance_id_number string read-only
secondary_insurer_payer_id string read-only
secondary_insurer_name string read-only
secondary_insurance_id_number string read-only
allow_overlapping boolean read-only
appt_is_break boolean read-only
cloned_from integer or null read-only ID of the original appointment which this appointment cloned from. If appointment was not cloned this field would be null.
extended_updated_at timestamp read-only The most recent update time among appointment itself, vitals and custom vitals
recurring_appointment boolean read-only Whether the appointment is a recurring appointment or not
base_recurring_appointment integer read-only ID of base appointment of recurring appointments
is_walk_in boolean optional If true, meaning patient walked-in for this appointment, not set up beforehand

/api/custom_vitals

Retrieve the custom vitals used by the authorizing doctor or practice group.

Required scopes: clinical

Required permissions: Access Clinical Notes

Practice group access: If the "share clinical templates" setting is on

Supported requests: GET

Filtering parameters:

Key Type Description
doctor integer Only retrieve custom vitals created by the given doctor
show_archived boolean If present when making a GET request without specifying an ID, archived results will be included. Not necessary when an ID is included in the URL.

Object key/values:

Key Type Always present Notes
archived boolean Yes Indicates that the object has been soft-deleted and should not be used.
data_type string Yes One of "text", "number" or "single_sel"
doctor integer Yes ID of the doctor who created this custom vital
id integer Yes
is_fraction_field boolean Yes
name string Yes
allowed_values array of strings No If data_type is "single_sel", this is the array of values in the select's dropdown
description string No
fraction_delimiter string No If is_fraction_field is true, this is the character separating the numerator and denominator (usually "/")
unit string No

/api/appointment_profiles

Create, modify, retrieve and delete appointment profiles for a doctor's calendar. Appointment profiles are for common kinds of appointments a doctor might have, such as "physical exam", which have a standard duration and should show up as the same color on the calendar.

Required scopes: calendar

Required permissions: Access Scheduling

Practice group access: If the "share appointment profiles" setting is on

Supported requests: GET, POST, PUT, PATCH, DELETE

Filtering parameters:

Key Type Description
doctor integer Only retrieve profiles for the given doctor
show_archived boolean If present when making a GET request without specifying an ID, archived results will be included. Not necessary when an ID is included in the URL.

Object key/values:

Key Type POST/PUT requests Notes
color string required
duration integer required Length of an appointment in minutes
name string required
online_scheduling boolean required Whether this profile should be availible for online scheduling
reason string required
sort_order integer optional Override the usual ordering of appointments in the patient's appointments page. Lower values are shown at the top.
archived boolean read-only Indicates that the object has been soft-deleted and should not be used.
id integer read-only

/api/appointment_templates

Create, modify, retrieve and delete appointment templates for a doctor's calendar. Appointment templates are blocks of time during which a doctor usually sees appointments with the same profile. These may have a longer duration then the corresponding profile, in which case they may allow multiple appointments to be booked during that period.

Required scopes: calendar

Required permissions: Access Scheduling

Practice group access: If the "share appointment profiles" setting is on

Supported requests: GET, POST, PUT, PATCH, DELETE

Keys requiring verbose=true: open_slots

Filtering parameters:

Key Type Description
available date Only list templates that are available for a given date, meaning there is an unscheduled block of time at least as long as the duration of the template's profile. The office parameter is required when using this parameter.
doctor integer Only retrieve templates for the given doctor
office integer List templates for the given office
profile integer List templates for the given appointment_profile instance
show_archived boolean If present when making a GET request without specifying an ID, archived results will be included. Not necessary when an ID is included in the URL.
strict any By default, queries with the available parameter assumes doctors can be double-booked as long as the appointments are in different exam rooms. Include strict to disable this assumption.
week_day string comma-separated integers. (0 = Monday, ..., 6 = Sunday)

Object key/values:

Key Type POST/PUT requests Notes
duration integer required Length of an appointment in minutes
exam_room integer required 1-based index for the exam room
office integer required
profile integer required ID of the appointment profile to default to
scheduled_time time required
week_day integer required 0 = Monday, ..., 6 = Sunday
week_days array of integers optional Array of integers that indicate week days. (0 = Monday, ..., 6 = Sunday)
archived boolean read-only Indicates that the object has been soft-deleted and should not be used.
id integer read-only
open_slots array of objects read-only Array of time intervals during which the template is available. Only computed if the available and verbose query parameters are passed. Note that only slots long enough to fit an appointment with the corresponding profile are included.

/api/doctors

Retrieve doctors in the same practice group as the authorizing doctor.

Required scopes: user

Required permissions: No special permissions are required

Practice group access: Yes

Supported requests: GET

Object key/values:

Key Type Always Present Notes
country string Yes Two-letter country code. Default is "US"
first_name string Yes
id integer Yes
last_name string Yes
specialty string Yes
cell_phone string No
email string No
group_npi_number string No
home_phone string No
job_title string No
npi_number string No If both this field and group_npi_number are set, prefer this field.
office_phone string No
practice_group integer No The ID of the practice group this user belongs to. This can be used to identify users in the same practice.
suffix string No
website string No
is_account_suspended boolean Yes Indicates the doctors account is suspended or not

/api/documents

Create, modify, retrieve and delete documents associated with a patient.

Required scopes: patients

Required permissions: Manage Patients Required

Practice group access: If the "share patients" setting is on

Supported requests: GET, POST, PUT, PATCH, DELETE

Filtering parameters:

Key Type Description
doctor integer List documents for a doctor (by ID)
patient integer List documents for a patient (by ID)
since timestamp Only retrieve documents that have been updated since a given date

Object key/values:

Key Type POST/PUT requests Notes
date date required
description string required
doctor integer required ID of the doctor who owns the document
document file required Files are passed using multipart/form-data encoding, but returned as URLs. See the tutorial for an example of uploading a file.
patient integer required ID of the patient the document concerns
metatags array of strings optional This should be quoted--e.g. '["a", "b"]'--since this endpoint requires multipart/form-data encoding
id integer read-only
updated_at timestamp read-only

/api/offices

Retrieve offices owned by the authorizing doctor's practice group. Offices can be modified to update the online_scheduling and online_timeslots settings to enable or disable the drchrono scheduling widget completely or for blocks of time.

Required scopes: user

Required permissions: No special permissions are required

Practice group access: Yes

Supported requests: GET, PATCH

Keys requiring verbose=true: online_timeslots

Filtering parameters:

Key Type Description
show_archived boolean If present when making a GET request without specifying an ID, archived results will be included. Not necessary when an ID is included in the URL.

Object key/values:

Key Type Writable Notes
online_scheduling boolean Yes Default is false
online_timeslots array of objects Yes Click on link for format
address string No
archived boolean No Indicates that the object has been soft-deleted and should not be used.
city string No
country string No Two-letter country code
doctor integer No ID of the doctor who owns the office
end_time time No Truncated the hour. Default is 24:00.
exam_rooms array of objects No Click on link for format
id integer No
name string No
phone_number string No
fax_number string No
start_time time No Truncated to the hour. Default is 00:00:00.
state string No Two-letter abbreviation
zip_code string No

/api/offices/:id/add_exam_room

Add an exam room to the office. Returns the entire updated office.

Required scopes: user

Required permissions: No special permissions are required

Practice group access: Yes

Supported requests: POST

Object key/values:

Key Type Required Notes
name string Yes
online_scheduling boolean No Default is false

/api/insurances

Search for insurance payers in the drchrono system which are available to the authorizing doctor. Note that some but not all payers are available to all doctors. This is intended for populating the primary_insurance, secondary_insurance and tertiary_insurance objects on /api/patients.

The payer_type filtering parameter is required.

Required scopes: user

Required permissions: No special permissions are required

Practice group access: Yes

Supported requests: GET

Filtering parameters:

Key Type Description
payer_type string One of emdeon, gateway or ihcfa
term string Search term, which can be either a partial name, partial ID or the state

Object key/values:

Key Type Always Present Notes
payer_name string Yes This field corresponds to the insurance_company field on an insurance object
payer_id string Yes This field corresponds to the insurance_payer_id field on an insurance object
state string No Two-letter abbreviation of the payer's headquarters' state

/api/custom_demographics

Retrieve custom demographics fields used by the authorizing doctor's practice group to add additional data to patient records.

Required scopes: patients

Required permissions: Manage Patients Required

Supported requests: GET, POST, PUT, PATCH

Practice group access: If the "share patients" setting is on

Filtering parameters:

Key Type Description
doctor integer List custom demographics defined by the doctor with the given ID
show_archived boolean If present when making a GET request without specifying an ID, archived results will be included. Not necessary when an ID is included in the URL.

Object key/values:

Key Type POST/PUT request Notes
id integer read-only
archived boolean optional Indicates that the object has been soft-deleted and should not be used.
doctor integer required
name string required
template_name string optional Custom Patient Demographics with template_name set can be inserted into clinical notes via Form Builder. Only letters (a-z or A-Z), numbers (0-9) or underscore(_) are allowed for template name.
allowed_values array of strings optional values must be seperated by comma ,
description string optional

/api/patients

Create, modify, retrieve and delete patients owned by doctors in the authorizing doctor's practice group.

Required scopes: patients

Required permissions: Manage Patients Required

Supported requests: GET, POST, PUT, PATCH, DELETE

Practice group access: If the "share patients" setting is on

Keys requiring verbose=true: primary_insurance, secondary_insurance, tertiary_insurance

Filtering parameters:

Key Type Description
date_of_birth date Limit to patients born on a given date
doctor integer List patients for the doctor with the given ID
email string
first_name string Case-insensitive and includes partial matches
gender string One of "Male", "Female", or "Other"
last_name string Case-insensitive and includes partial matches
offices string If an office ID or comma-separated list of office IDs is passed, limit results to patients who have an appointment at one of the given offices
since timestamp Only retrieve patients that have been updated since a given date

Object key/values:

Key Type POST/PUT request Notes
date_of_birth date optional
doctor integer required ID of the patient's primary provider. Other doctors in the practice group may have access to the patient's chart.
gender string required One of "Male", "Female", or "Other"
address string optional
cell_phone string optional
chart_id string optional Automatically set using first & last names if absent
city string optional
custom_demographics array of objects optional Click on link for format. NOT the same as the object returned by /api/custom_demographics.
email string optional
emergency_contact_name string optional
emergency_contact_phone string optional
emergency_contact_relation string optional
employer string optional
employer_address string optional
employer_city string optional
employer_state string optional Two-letter abbreviation
employer_zip_code string optional
ethnicity string optional One of "blank", "hispanic", "not_hispanic" or "declined"
first_name string optional
home_phone string optional
last_name string optional
middle_name string optional
nick_name string optional
patient_photo file optional
patient_photo_date date optional Cannot be passed without patient_photo
patient_payment_profile string optional One of "", "Cash", "Insurance", "Insurance Out of Network", "Auto Accident" or "Worker's Comp".
Note: Patient must already have either primary_insurance or secondary_insurance or new primary_insurance or secondary_insurance is passed in request if Insurance, Auto Accident or Worker's Comp payment profiles are chosen.
preferred_language string optional Use ISO 639 alpha-3 codes
primary_care_physician string optional Referring doctor for this patent.
primary_insurance object optional Click link for format. Warning: Changing insurance information may make past appointments unbillable. Insurance data is also unvalidated; you should use the /api/insurances endpoint to find the appropriate insurance payer.
race string optional One of "blank", "indian", "asian", "black", "hawaiian", "white" or "declined"
responsible_party_name string optional
responsible_party_relation string optional
responsible_party_phone string optional
responsible_party_email string optional
secondary_insurance object optional Click link for format. Warning: Changing insurance information may make past appointments unbillable. Insurance data is also unvalidated; you should use the /api/insurances endpoint to find the appropriate insurance payer.
social_security_number string optional
state string optional Two-letter abbreviation
tertiary_insurance object optional Click link for format. Warning: Changing insurance information may make past appointments unbillable. Insurance data is also unvalidated; you should use the /api/insurances endpoint to find the appropriate insurance payer.
zip_code string optional
id integer read-only
offices array of integers read-only IDs of every office this patient has been to
default_pharmacy string optional ncpdp id of patient's default pharmacy
patient_flags list of objects read-only Click link for format.
updated_at timestamp read-only

/api/patients/:id/ccda

Returns the patient's data as C-CDA XML.

Required scopes: patients

Required permissions: No special permissions required

Practice group access: If the "share patients" setting is on

Supported requests: GET

/api/patients/:id/qrda1

Returns the patient's data as QRDA-1 XML.

Required scopes: patients

Required permissions: No special permissions required

Practice group access: If the "share patients" setting is on

Supported requests: GET

Filtering parameters:

Key Type Description
start_date date Start date for QRDA-1
end_date date End date for QRDA-1

/api/patients_summary

Like the /api/patients endpoint, but only includes the minimum data necessary for non-clinical and non-billing tasks such as scheduling appointments.

Required scopes: patients:summary

Required permissions: Manage Patients Required for write access only

Practice group access: If the "share patients" setting is on

Supported requests: GET, POST, PUT, PATCH, DELETE

Filtering parameters:

Key Type Description
date_of_birth date Limit to patients born on a given date
doctor integer List patients for the doctor with the given ID
first_name string Case-insensitive and includes partial matches
gender string One of "Male", "Female", or "Other"
last_name string Case-insensitive and includes partial matches
since timestamp Only retrieve patients that have been updated since a given date

Object key/values:

Key Type POST/PUT request Notes
date_of_birth date required
doctor integer required ID of the patient's primary provider. Other doctors in the practice group may have access to the patient's chart.
gender string required One of "Male", "Female", or "Other"
chart_id string optional Automatically set using first & last names if absent
first_name string optional
last_name string optional
id integer read-only

/api/patient_payments

Retrieve or create patient payments.

Required scopes billing:patient-payment

Required permissions: Access Billing, Show Billing Tab, Access Patients Payments

Practice group access: If the "share patients" setting is on

Supported requests: GET, POST

Filtering parameters:

Key Type Description
doctor integer Only retrieve payments for the doctor with the specified id
patient integer Only retrieve payments for the patient with the specified id
since timestamp Only retrieve payments that have been updated since a given date

Object key/values:

Key Type Required in POST Notes
appointment integer optional Should exist at the same time with line_item
amount decimal required Amount of cash for this payment, cannot be zero
created_at timestamp read-only
created_by integer read-only
doctor integer optional
id integer read-only
line_item integer optional Should exist at the same time with appointment
notes string optional
patient integer required
payment_method string optional
posted_date date read-only
received_date date optional
trace_number string optional
updated_at timestamp read-only

/api/patient_payment_log

Retrieve the log entries for patient payments.

Required scopes: billing

Required permissions: Access Billing, Show Billing Tab

Practice group access: If the "share patients" setting is on

Supported requests: GET

Filtering parameters:

Key Type Description
doctor integer Only retrieve payments for the doctor with the specified id
office integer Only retrieve payments for the office with the specified id
since timestamp Only retrieve payments that have been updated since a given date

Object key/values:

Key Type Always Present Notes
patient integer Yes The /api/patients associated with the payment.
doctor integer Yes The /api/doctors associated with the patient
appointment integer Yes The /api/appointments associated with the payment.
amount decimal Yes
payment_method string Yes Possible values
created_by integer No The /api/users who created the payment.
action string Yes Possible values
source string Yes
updated_at timestamp Yes

/api/reminder_profiles

Create, modify, retrieve or delete reminder profiles for the authorizing doctor. A reminder profile is a default set of reminders to send to patients before an appointment. They can be applied to an appointment using the api/appointments endpoint.

Required scopes: calendar

Practice group access: If the "share reminder profile" setting is on

Required permissions: Access Scheduling

Supported requests: GET, POST, PUT, PATCH, DELETE

Object key/values:

Key Type POST/PUT requests Notes
doctor integer required ID of the doctor who created the profile. Other doctors in the practice group may have access to their profiles.
name string required
reminders array of objects required Click on link for format
id integer read-only

/api/users

Retrieve the users in the practice group of the authorizing doctor. The /api/users/current redirects to /api/users/:current_user_id.

Required scopes: None required

Required permissions: No special permissions required

Practice group access: Yes

Supported requests: GET

Object key/values:

Key Type Always Present Notes
doctor integer Yes For staff members, this is their primary physician's ID. For doctors, it is their own ID.
id integer Yes
is_doctor boolean Yes Mutually exclusive with is_staff
is_staff boolean Yes Mutually exclusive with is_doctor
username string Yes
practice_group integer No The ID of the practice group this user belongs to. This can be used to identify users in the same practice.
premissions objects Yes Permissions this user has. Click on link for format.

/api/transactions

Retrieve the billing information associated with appointments with the authorizing doctor's practice group.

Required scopes: billing

Required permissions: Access Billing, Show Billing Tab

Practice group access: If the "share patients" setting is on

Supported requests: GET

Filtering parameters:

Key Type Description
doctor integer Only retrieve transactions for the doctor with the specified id
office integer Only retrieve transactions for the office with the specified id
since timestamp Only retrieve transactions that have been updated since a given date

Object key/values:

Key Type Always Present Notes
adjustment decimal Yes Adjustment from total billed
appointment integer Yes Appointment ID
allowed decimal Yes Amount allowed by insurance
balance_ins decimal Yes Insurance balance
balance_pt decimal Yes Patient balance
balance_total decimal Yes Total balance
billed decimal Yes Total billed
billing_status string Yes One of "", "Incomplete Information", "In Process Emdeon", "In Process iHCFA", "In Process Gateway", "Rejected Emdeon", "Rejected iHCFA", "Rejected Gateway", "In Process Payer", "Payer Acknowledged", "Rejected Payer", "Paid in Full", "Partially Paid", "Coordination of Benefits", "ERA Received", "ERA Denied",
code string Yes
denied_flag boolean Yes
diagnosis_pointers list Yes List of 4 diagnosis pointers, each integers
doctor integer Yes Doctor ID
id integer Yes
ins1_paid decimal Yes Amount paid by patient's primary insurer
ins2_paid decimal Yes Amount paid by patient's secondary insurer
ins3_paid decimal Yes Amount paid by patient's tertiary insurer
ins_total decimal Yes Amount paid by patient's insurers
modifiers list Yes List of 4 code modifiers, each strings
paid_total decimal Yes Total amount paid
patient integer Yes Patient ID
price decimal Yes Price of procedure
procedure_type string Yes One of "CPT", "HCPCS", "Custom"
pt_paid decimal Yes Amount paid by patient
quantity decimal Yes
units string Yes Default is 'UN'
posted_date timestamp Yes
updated_at timestamp Yes
service_date date No Date on which the service was rendered
description string No
expected_reimbursement decimal No

/api/allergies

Retrieve allergies for patients owned by the authorizing doctor's practice group.

Required scopes: clinical

Required permissions: Access Clinical Notes

Practice group access: If the "share patients" setting is on

Supported requests: GET, POST, PUT, PATCH

Keys requiring verbose=True: description

Filtering parameters:

Key Type Description
patient integer Only retrieve transactions for the patient with the specified id

Object key/values:

Key Type POST/PUT requests Notes
doctor integer required ID of the doctor who diagnosed the allergy
id integer read-only
patient integer required Patient ID
description string optional Description of the allergy, such as "Cat hair"
notes string optional Any additional notes from the provider
reaction string optional Short description of the patient's allergic reaction, such as "Hives"
rxnorm string optional If the allergy is a drug allergy, this is the RxNorm code of the drug
snomed_reaction string optional SNOMED code for the reaction. For possible SnoMED codes, please see this link from PHIN VADS
status string optional If present, one of "active" or "inactive". If omitted in writing, default to active

/api/medications

Retrieve medications for patients owned by the authorizing doctor's practice group.

Required scopes: clinical

Required permissions: Access Clinical Notes

Practice group access: If the "share patients" setting is on

Supported requests: GET, POST, PUT, PATCH

Filtering parameters:

Key Type Description
patient integer Only retrieve transactions for the patient with the specified id

Object key/values:

Key Type POST/PUT requests Notes
daw boolean optional If True, the prescription should be dispensed as written and not substituted
doctor integer required Prescribing doctor ID
id integer read-only
name string optional
patient integer required Patient ID
prn boolean optional If True, the medication should be taken when necessary
appointment integer optional Appointment ID corresponding to the initial prescription
date_prescribed date optional
date_started_taking date optional
date_stopped_taking date optional
dispense_quantity decimal optional
dosage_quantity string optional Please note, this used to be an decimal field, you can still pass decimal value to it. Or you can pass in some formatted string if needed.
dosage_units string optional
notes string optional Any additional notes from the provider
frequency string optional Frequency of administration
indication string optional
number_refills integer optional
order_status string optional One of "", "Ordered", "Administered during visit", "Electronic eRx Sent", "Phoned into Pharmacy", "Faxed to Pharmacy", "Paper Rx", "Prescription Printed", "Discontinued", "Prescribed by other Dr" or "Over the Counter". If omitted in writing, default to ""
pharmacy_note string optional
route string optional Route of administration
rxnorm string optional RxNorm code for the medication
signature_note string optional
status string optional If present, one of "active" or "inactive". If omitted in writing, default to active

/api/medications/:id/append_to_pharmacy_note

Allows appending a message to the pharmacy_note section of the prescription, in a new paragraph. Returns the new pharmacy_note text.

Required scopes: clinical

Required permissions: Access Clinical Notes

Practice group access: If the "share patients" setting is on

Supported requests: PATCH

Request parameters:

Key Type Description
text string Text to append

/api/problems

Retrieve problems (e.g. diseases) for patients owned by the authorizing doctor's practice group.

Required scopes: clinical

Required permissions: Access Clinical Notes

Practice group access: If the "share patients" setting is on

Supported requests: GET, POST, PUT, PATCH

Filtering parameters:

Key Type Description
patient integer Only retrieve transactions for the patient with the specified id

Object key/values:

Key Type POST/PUT requests Notes
doctor integer required ID of the doctor who diagnosed the problem
icd_version integer optional Either 9 or 10. If omitted in writing, default to 10.
id integer read-only
patient integer required Patient ID
date_changed date optional
date_diagnosis date optional
date_onset date optional
description string optional
icd_code string optional The ICD9 or ICD10 code for the problem
info_url URL read-only External URL with more information about the problem, intended for patient education
name string optinal Name of the problem
notes string optional Any additional notes by the provider
status string optional Either active, inactive or resolved. If omitted in writing, default to active
snomed_ct_code string optional SnoMED code for the problem

/api/amendments

Retrieve, modify, create or delete amendments to a patient's clinical records.

You can only interact with amendments created by your API application, not those created through the front-end.

Required scopes: clinical

Required permissions: Access Clinical Notes

Practice group access: If the "share patients" setting is on

Supported requests: GET, POST, PUT, PATCH, DELETE

Filtering parameters:

Key Type Description
appointment integer Only retrieve amendments for the appointment with the specified id
patient integer Only retrieve amendments for the patient with the specified id

Object key/values:

Key Type POST/PUT requests Notes
amendment_name string required
amendment_file string required A PDF file containing the amended information for the patient's record
doctor integer required ID of the doctor who owns the amendment
patient integer required ID of the patient to whom the ammendment applies
appointment integer optional ID of the appointment to which the amendment applies, if any. If present, the amendment_file will be appended to the clinical note for this appointment.
comments string optional
id integer read-only

/api/clinical_note_templates

Retrieve clinical note templates.

Required scopes: clinical

Required permissions: Access Clinical Notes

Practice group access: If the "share clinical templates" setting is on

Supported requests: GET

Keys requiring verbose=true: clinical_note_fields

Filtering parameters:

Key Type Description
show_archived boolean If present when making a GET request without specifying an ID, archived results will be included. Not necessary when an ID is included in the URL.

Object key/values:

Key Type Always present Description
archived boolean Yes Indicates that the doctor has soft-deleted this template, and will not use it for future appointments
doctor integer Yes
id integer Yes
is_onpatient boolean Yes
is_persistent boolean Yes
name string Yes
order object Yes Click on link for format
clinical_note_fields array of objects Yes Click on link for format
updated_at timestamp Yes

/api/clinical_notes

Retrieve the clinical note for an appointment as structured data. Note that you need to pass verbose=true for the values; see the field clinical_note_sections below for details. This endpoint returns 5 objects per page, and the maximum page size is 20.

Required scopes: clinical

Required permissions: Access Clinical Notes

Practice group access: If the "share patients" setting is on

Supported requests: GET

Filtering parameters:

Key Type Description
date date Only retrieve clinical notes whose appointment occurs on the given date
date_range date range Retrieve clinical notes in a time period (inclusive). Cannot be longer than 190 days, unless it is in the past.
office integer Only retrieve clinical notes for the office with the given ID
patient integer Only retrieve clinical notes for the patient with the given ID
show_archived boolean If present when making a GET request without specifying an ID, archived results will be included. Not necessary when an ID is included in the URL.
since timestamp Only retrieve clinical notes that have been updated since a given date

Object key/values:

Key Type Always present Description
archived boolean Yes Indicates that the appointment which the note is for has been deleted
appointment integer Yes
patient integer Yes
clinical_note_sections array of objects Yes Click on link for format

/api/clinical_note_field_types

Retrieve the fields which are used when charting an appointment.

Required scopes: clinical

Required permissions: Access Clinical Notes

Practice group access: If the "share clinical templates" setting is on

Supported requests: GET

Filtering parameters:

Key Type Description
clinical_note_template integer Only retrieve field types belonging to the specified /api/clinical_note_templates object
show_archived boolean If present when making a GET request without specifying an ID, archived results will be included. Not necessary when an ID is included in the URL.

Object key/values:

Key Type Always present Description
archived boolean Yes Indicates that the field has been soft-deleted by the doctor and will not be used in future notes
appointment integer Yes ID of the /api/appointments object the value corresponds to
clinical_note_template integer Yes ID of the /api/clinical_note_templates object that the field belongs to
data_type string Yes One of "", "Checkbox", "NullCheckbox", "String", "TwoStrings", "FreeDraw", "Photo", "Header", "Subheader"
id integer Yes
name string Yes
required boolean Yes Indicates that a note should not be locked unless a value is provided for this field
comment string No

/api/clinical_note_field_values

Retrieve the values entered by the doctor when charting a particular appointment.

Required scopes: clinical

Required permissions: Access Clinical Notes

Practice group access: If the "share patients" setting is on

Supported requests: GET

Filtering parameters:

Key Type Description
appointment integer Only retrieve field values belonging to the specified /api/appointments object (See also /api/clinical_notes)
clinical_note_field integer Only retrieve field values belonging to the specified /api/clinical_note_field_types object
clinical_note_template integer Only retrieve field values belonging to the specified /api/clinical_note_templates object
show_archived boolean If present when making a GET request without specifying an ID, archived results will be included. Not necessary when an ID is included in the URL.

Object key/values:

Key Type Always present Description
id integer Yes
clinical_note_field integer Yes ID of the /api/clinical_note_field_types object that the value belongs to
value string Yes Value entered by the doctor. Interpretation varies by field type.

/api/messages

View, edit and create messages in the doctor's message center.

Required scopes: messages

Required permissions: Access Message Center

Practice group access: If the "share patients" setting is on

Supported requests: GET, POST, PUT, PATCH, DELETE

Filtering parameters:

Key Type Description
received_since timestamp Only retrieve messages that have been received since a given date
updated_since timestamp Only retrieve messages that have been updated since a given date
doctor integer Only retrieve messages in the given doctor's message center
owner integer Only retrieve messages owned by the given user, which may be a staff member of the doctor
patient integer Only retrieve messages concerning the given patient
responsible_user integer Only retrieve messages assigned to the given user, which may be a staff member of the doctor
show_archived boolean If present when making a GET request without specifying an ID, archived results will be included. Not necessary when an ID is included in the URL.

Object key/values:

Key Type POST/PUT requests Notes
doctor integer required
title string required
attachment file optional Files are passed using multipart/form-data encoding, but returned as URLs. See the tutorial for an example of uploading a file.
owner integer optional The /api/users object who owns the message, who may be the doctor themselves or one of their staff members
patient integer optional The /api/patients object that the message concerns, if applicable
responsible_user integer optional The /api/users object who has been assigned to process the message, who may be the doctor themselves or one of their staff members
type string optional See here for allowed values
archived boolean read-only If true, indicates that the message has been soft-deleted
id integer read-only
read boolean read-only
received_at boolean read-only
updated_at boolean read-only
starred boolean read-only
workflow_step string read-only Used by doctors and their staff to keep track of what step of processing the message is in
message_notes array of objects optional Click on link for format

/api/prescription_messages

Retrieve prescription messages for a given doctor and patient

Required scopes: clinical

Required permissions: Access Clinical Notes

Practice group access: If the "share patients" setting is on

Supported requests: GET

Filtering parameters:

Key Type Description
since timestamp Only retrieve messages that have been received/sent since a given date
doctor integer optional
patient integer optional
parent_message integer Only retrieve prescription messages with the given parent

Object key/values:

Key Type Always present Description
id integer Yes
doctor integer Yes
message_direction string Yes Possible values are Outgoing and Incoming.
message_type string Yes Possible values are NewRx for outgoing new prescriptions, RefillRequest for incoming refill requests, RefillResponse for outgoing refill responses, Error for incoming errors, Status and Verify for incoming status reports from Surescripts.
message_status string Yes Message status for Incoming and Outgoing values. Success message for message_type are: NewRx : Sent, RefillRequest : Received, RefillResponse : Sent.
parent_message_id integer No Refers to the parent message, used for refill responses and incoming error/status reports.
patient integer No An optional field which refers to a patient.
pharmacy string Yes NCPDP ID of the pharmacy.
created_at date Yes Used to filter by since parameter.
json_data object No Data sent along with NewRx, RefillRequest, and RefillResponses messages. The format varies, but most likely it will contain BenefitsCoordination section with insurance info and MedicationPrescribed with medication info. Patient, Pharmacy, and Prescriber are also usually present. Example

/api/fee_schedules

Retrieve fee schedules for doctors

Required scopes: billing

Required permissions: Access Billing

Practice group access: If the share fee schedule setting is on

Supported requests: GET

Filtering parameters:

Key Type Description
since timestamp Only retrieve fee schedules that have been created/updated since a given timestamp
doctor integer Only retrieve fee schedules created by the given doctor
payer_id integer Only retrieve fee schedules associated with the given payer
code_type string Only retrieve fee schedules with the given code type. Choices are between CPT, HCPCS, ICD9, ICD10, Custom, Revenue
code string Only retrieve fee schedules with the given code.

Objecct key/values:

Key Type Always present Description
id integer Yes
doctor integer Yes
code string Yes
code_type string Yes
cpt_hcpcs_modifier1 string Yes
cpt_hcpcs_modifier2 string Yes
cpt_hcpcs_modifier3 string Yes
cpt_hcpcs_modifier4 string Yes
office integer Yes
ndc_code string Yes
ndc_quantity decimal Yes
ndc_units string Yes
base_price decimal Yes
insured_price decimal Yes
cash_price decimal Yes
insured_out_of_network_price decimal No
payer_id string Yes
plan_name string Yes
allowed_amount decimal Yes
billing_description string Yes
description string Yes
picklist_category string Yes
created_at timestamp Yes
updated_at timestamp Yes

/api/comm_logs

Retrieve phone call logs for doctors

Required scopes: calendar

Required permissions: Access Scheduling

Practice group access: If "Share Patients" setting is turned on

Supported requests: GET, POST, PUT, PATCH

Filtering parameters:

Key Type Description
doctor integer Only retrieve phone call logs for the doctor with given ID
patient integer Only retrieve phone call logs for the doctor with given ID
since integer Only retrieve phone call logs that have been updated since a given date

Object key/values:

Key Type POST/PUT Request Notes
appointment integer optional Appointment related with the phone call log
archived boolean read-only If this phoen call log is archived or not
author integer read-only User that modified the phone call log
cash_charged decimal optional Amount of cash needs to be charged
created_at timestamp read-only
doctor integer required
duration integer optional Duration of the phone call
id integer read-only
message string optional Additional message for the phone call log
patient integer required
scheduled_time timestamp optional If appointment is specified, this field will be set as the scheduled_time of that appointment
title string optional Title of the phone call log
type string optional Type of the phone call log
updated_at timestamp read-only

/api/mu_2015_report

Retrieve MU 2015 report for doctors

Required scopes: clinical

Required permissions: Access Clinical Notes

Practice group access: No

Supported requests: GET

Filtering parameters:

Key Type Description
date_range date range
stage integer Can be either 1 or 2

Object key/values:

Key Type Always present Description
start_date timestamp Yes
end_date timestampe Yes
stage integer Yes
objectives list of objects Yes objectives of report

IFrame integration

Beta: These features are still in beta and should not be considered as stable as the main API.

Certain applications may integrate with either the patient detail page or the clinical note page, providing extra information about a patient or the appointment for the doctor. See the tutorial for how to get access to this feature.

Endpoints

/api/iframe_integration

Making a POST request to this endpoint causes the application to show up on the navigation bar of the patient detail page for the authorizing doctor, allowing the doctor to use the iframe integration. A DELETE request undoes this.

See Responses for handling 302 responses.

Required scopes: None

Required permissions: No special permissions required

Supported requests: POST, DELETE

Pages Featuring Iframes

The Iframe can be embedded in any or all of these pages. A different URL can be specified for each. When the Iframe is included, the query parameters specified below will be appended to the URL.

/patients/:id

Query Parameters:

Key Type Always present Notes
user_id integer Yes This may not be the doctor, e.g., in case of staff
doctor_id integer Yes
iat integer Yes Unix timestamp at which the request was initiated. This is included to protect against replay attacks.
jwt JSON Web Token Yes Signs the other parameters using your client_secret and the HS256 algorithm. This verifies that the request originates from drchrono and has not been tampered with.
patient_id integer Yes
practice_id integer No ID of the practice group to which the doctor belongs, if any

Example:

Iframe on the patient page

/clinical_note/edit/:id

Query Parameters:

Key Type Always present Notes
appointment_id integer Yes
doctor_id integer Yes
iat integer Yes Unix timestamp at which the request was initiated. This is included to protect against replay attacks.
jwt JSON Web Token Yes Signs the other parameters using your client_secret and the HS256 algorithm. This verifies that the request originates from drchrono and has not been tampered with.
patient_id integer Yes
practice_id integer No ID of the practice group to which the doctor belongs, if any

Example:

Iframe on the clinical note page

API Webhooks

Introduction

This documentation is intended as a detailed reference for the precise behaviour of drchrono API webhooks.

In order to use drchrono API webhooks, you first need to have an API application on file (even if it is in Test Model). Each API webhook is associated with one API application, go to here to set up both API applications and webhooks!

Once you registered an API application, you will see webhook section in each saved API applications. Create a webhook and register some events there and save all the changes, then you are good to go!

Webhooks setup

All fields under webhooks section are required.

Callback URL Callback URl is used to receive all hooks when subscribed events are triggered. This should be an URL under your control.

Secret token Secret token is used to verify webhooks, this is very important, please set something with high entropy. Also we will talk more about this later.

Events

Events is used to register events you want to receiver notification when they happen. Currently we support following events.

Event name Event description
APPOINTMENT_CREATE We will deliver a hook any time an appointment is created
APPOINTMENT_MODIFY We will deliver a hook any time an appointment is modified
PATIENT_CREATE We will deliver a hook any time a patient is created
PATIENT_MODIFY We will deliver a hook any time a petient is modified
PATIENT_PROBLEM_CREATE We will deliver a hook any time a patient problem is created
PATIENT_PROBLEM_MODIFY We will deliver a hook any time a patient problem is modified
PATIENT_ALLERGY_CREATE We will deliver a hook any time a patient allergy is created
PATIENT_ALLERGY_MODIFY We will deliver a hook any time a patient allergy is modified
PATIENT_MEDICATION_CREATE We will deliver a hook any time a patient medication is created
PATIENT_MEDICATION_MODIFY We will deliver a hook any time a patient medication is modified
CLINICAL_NOTE_LOCK We will deliver a hook any time a clinical note is locked
CLINICAL_NOTE_UNLOCK We will deliver a hook any time a clinical note is unlocked

Webhooks verification

In order to make sure the callback URL in webhook is under your control, we added a verification step before we send any hooks out to you.

Verification can be done by clicking "Verify webhook" button in webhooks setup page. After you click the button, we will send a GET request to the callback URL, and we expect a 200 JSON response, also in JSON response body, there should be a key called secret_token exists, and its value should be same as the secret token you specified in setup page. Otherwise, verification would fail.

Note: Verification would be needed when webhook is first created and anytime callback URl is changed.

Webhooks header and body

Header

Key Value
X-drchrono-event Event that triggered this hook, could be any one event above or PING
X-drchrono-signature Secret token associated with this webhook
X-drchrono-delivery ID of this delivery

Body

Key Value
receiver This would be an JSON representation of the webhook
object This would be an JSON representation of the object related to the triggered event, this would share same serializer as drchrono API

Webhooks ping and deliveries

PING:

You can always ping your webhook to check things, by clicking the "Ping webhook" button in webhook setup page. And a hook with header X-drchrono-event: PING would be sent to the callback URL.

Deliveries:

You can check recent deliveries by clicking the "deliveries" link in webhook setup page. And you can resend a hook by clicking "redeliver" button after select a specific delivery.

Webhooks delivery mechanism

We will delivery a hook the moment a subscribed event is triggered. We will not record any response header or body you send back after you receive the hook. However we only consider the response status code. We will consider any 2xx responses as successfully delivered. Any other responses, like 302 would be considered failing. And we will try to redeliver unsuccessfully delivered hooks 3 times, first redeliver happens at 1 hour after the initial event, second receliver happens 3 hours after the initial event, and the third redeliver happens 7 hours after the initial event. After these redeliveries, if the delivery is still unsuccessful, you have to redeliver it by hand.

Webhooks secure

You may want to secure your webhooks to only consider requests send out from drchrono. And this is where secret_token is needed in request header. Try to set the secret_token to something with high entropy, a good example could be taking the output of ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'. After this, you might want to verify all request headers you received on your server with this token.