Table of Contents

Introduction

This document is intended as a detailed reference for the precise behavior of the DrChrono v2 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:

URL Request Type Side-Effects Response Code (success) Response Code (failure) Response Content
:endpoint GET None 200 403 Paginated list of all objects at that endpoint to which requester has access (Note: 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 200 400, 403 or 409 Object after modification
:endpoint/:id PATCH Update only included values 200 400, 403 or 409 Object after modification
: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:

{
  "count": integer,                     // total items available
  "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.

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 both 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 API@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 v2, 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

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

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

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", "Cancelled", "Complete", "Confirmed", "In Session", "No Show", "Not Confirmed", or "Rescheduled"
vitals object optional Click on link for format
billing_status string 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
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

/api/custom_vitals

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

Required scopes: clinical

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

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

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

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

/api/documents

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

Required scopes: patients

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

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

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

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

Supported requests: GET

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 Always Present Notes
archived boolean Yes Indicates that the object has been soft-deleted and should not be used.
doctor integer Yes
id integer Yes
allowed_values array of strings No
description string No
name string No

/api/patients

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

Required scopes: patients

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
created_at timestamp read-only
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
patient_photo file optional
patient_photo_date date optional Cannot be passed without patient_photo
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
updated_at timestamp read-only

/api/patients/:id/ccda

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

Required scopes: patients

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

Supported requests: GET

/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

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_payment_log

Retrieve the log entries for patient payments.

Required scopes: billing

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

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

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
plan_type string 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.

/api/transactions

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

Required scopes: billing

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'
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

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

Supported requests: GET

Filtering parameters:

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

Object key/values:

Key Type Always Present Notes
doctor integer Yes ID of the doctor who diagnosed the allergy
id integer Yes
patient integer Yes Patient ID
description string No Description of the allergy, such as "Cat hair"
notes string No Any additional notes from the provider
reaction string No Short description of the patient's allergic reaction, such as "Hives"
rxnorm string No If the allergy is a drug allergy, this is the RxNorm code of the drug
snomed_reaction string No SNOMED code for the reaction
status string No If present, one of "active" or "inactive"

/api/medications

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

Required scopes: clinical

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

Supported requests: GET

Filtering parameters:

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

Object key/values:

Key Type Always Present Notes
daw boolean Yes If True, the prescription should be dispensed as written and not substituted
doctor integer Yes Prescribing doctor ID
id integer Yes
name string Yes
patient integer Yes Patient ID
prn boolean Yes If True, the medication should be taken when necessary
appointment integer No Appointment ID corresponding to the initial prescription
date_prescribed date No
date_started_taking date No
date_stopped_taking date No
dispense_quantity decimal No
dosage_quantity decimal No
dosage_units string No
notes string No Any additional notes from the provider
frequency string No Frequency of administration
indication string No
number_refills integer No
order_status string No 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"
pharmacy_note string No
route string No Route of administration
rxnorm string No RxNorm code for the medication
signature_note string No
status string No If present, one of "active" or "inactive"

/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

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

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

Supported requests: GET

Filtering parameters:

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

Object key/values:

Key Type Always Present Notes
doctor integer Yes ID of the doctor who diagnosed the problem
icd_version integer Yes Either 9 or 10
id integer Yes
patient integer Yes Patient ID
date_changed date No
date_diagnosis date No
date_onset date No
description string No
icd_code string No The ICD9 or ICD10 code for the problem
info_url URL No External URL with more information about the problem, intended for patient education
name string No Name of the problem
notes string No Any additional notes by the provider
status string No

/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

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

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.

Required scopes: clinical

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

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

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

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

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

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

Free API Development Terms and Conditions