Table of Contents

Introduction

This document is intended as a detailed reference for the precise behavior of the DrChrono v4 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 version map or 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 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 v4, 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, extended_updated_at, reminders, status_transitions, vitals

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
status string Only retrieve appointments that have the given status
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"
status_transitions object read_only Records of status changes, click on link for format
vitals object optional Click on link for format
supervising_provider integer optional Supervising provider of appointment if set
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 optional
billing_notes list of objects 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 optional
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
is_virtual_base boolean read-only Indicates if the appointment/break is virtual base.
custom_fields array of objects optional Custom appointment fields

/api/custom_vitals

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

Required scopes: clinical, settings

Required permissions: Access Clinical Notes, Settings

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

Required permissions: Access Scheduling, Settings

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
billing_profile integer optional Billing profile id to link to the appointment profile

/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, settings

Required permissions: Access Scheduling, Settings

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_days array of integers required 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/billing_profiles

Retrieve billing profiles that the authorizing doctor has access to

Required scopes: billing

Required permissions: Access Billing, Show Billing Tab

Practice group access: When "share billing profiles" is turned on

Supported requests: GET

Filtering parameters:

Key Type Description
doctor integer Only retrieve billing profiles belong to specifc doctor

Object key/values:

Key Type Always Present Notes
archived boolean Yes
cpt_codes array of objects Yes Click on link for more information
created_at timestamp Yes
custom_procedure_codes array of objects Yes Click on link for more information
doctor integer Yes
hcpcs_codes array of objects Yes Click on link for more information
icd9_codes array of string Yes
icd10_codes array of string Yes
id integer Yes
name string Yes
updated_at timestamp Yes

/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.
practice_group_name string Yes The name of the practice group this user belongs to.
profile_picture string No The url to the doctor's profile picture
suffix string No
timezone string Yes
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
archived boolean read-only DELETE operation will set this field to true
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/consent_forms

Retrieve and modify patient consent forms within the authorizing doctor's practice group

Required scopes: patients

Required permissions: Manage Patients

Supported requests: GET, POST, PUT, PATCH

Practice group access: Yes, when "share consent forms" is enabled

Filtering parameters:

Key Type Description
doctor integer Retrieve consent forms belong to specified doctor

Object key/values:

Key Type POST/PUT requests Notes
archived boolean read-only
`assign_by_default boolean optional If true, consent form will always be automatically assigned to appointments
created_at timestamp read-only
doctor integer required
id integer read-only
is_mandatory boolean optional If true, consent form must be signed prior to appointment check in
order integer read-only The order of consent forms that will show in management screen
title string required
updated_at timestamp read-only
uri file required Files are passed using multipart/form-data encoding, but returned as URLs.

/api/consent_forms/:id/apply_to_appointment

Assign / apply a consent form to appointments

Required scopes: patients

Required permissions: Manage Patients

Supported requests: POST

Practice group access: Yes, when "share consent forms" is enabled

Object key/values:

Key Type POST requests Notes
appointment integer required The appointment that the consent form will be applied to

/api/consent_forms/:id/unapply_from_appointment

Unassign / unapply a consent form to appointments

Required scopes: patients

Required permissions: Manage Patients

Supported requests: POST

Practice group access: Yes, when "share consent forms` is enabled

Object key/values:

Key Type POST requests Notes
appointment integer required The appointment that the consent form will be unapplied from

/api/custom_insurance_plan_names

Retrieve custom insurance plan names used by the authorizing doctor's practice group

Required scopes: settings

Required permissions: Settings Required

Supported requests: GET

Practice group access: Yes, when "custom insurance plan name" is enabled

Filtering parameters:

Key Type Description
doctor integer Retrieve custom insurance plan name created by specific doctor
user integer Retrieve custom insurance plan name created by specific user
name string Retrieve custom insurance plan names that contains specific string
since timstamp Retrieve custom insurance plan names that are updated after specific timestamp
show_archived boolean Retrieve archived names along with unarchived ones

Object key/values:

Key Type Always Present Notes
archived integer Yes
created_at timestamp Yes
doctor integer Yes Doctor who created the custom insurance plan name
id integer Yes
insurance_plan_name string Yes Custom name
updated_at timestampe Yes
user integer Yes User who created the custom insurance plan name

/api/custom_appointment_fields

Retrieve or create custom appointment fields used by the authorizing doctor's practice group

Required scopes: clinical, settings

Required permissions: Access Clinical Notes, Settings 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 appointment fields 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
archived boolean read-only Indicates that the object has been soft-deleted and should not be used.
doctor integer required
field_name string required
field_desc string optional Description of this custom field
id integer read-only
order integer read-only
created_at timestamp read-only
updated_at timestamp read-only

/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, settings

Required permissions: Manage Patients, Settings 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: auto_accident_insurance, primary_insurance, secondary_insurance, tertiary_insurance, custom_demographics, patient_flags, patient_flags_attached, referring_doctor, workers_comp_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
ethnicity string Only retrieve patients with given ethinicity
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
preferred_language string Only retrieve patients with given preferred language
race string Only retrieve patients with given race
since timestamp Only retrieve patients that have been updated since a given date
show_inactive boolean Retrieve inactive patients along with active ones

Object key/values:

Key Type POST/PUT request Notes
auto_accident_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.
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.
default_pharmacy string optional ncpdp id of patient's default pharmacy
disable_sms_messages boolean optional
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
id integer read-only
last_name string optional
middle_name string optional
nick_name string optional
offices array of integers read-only IDs of every office this patient has been to
patient_flags list of objects read-only Click link for format.
patient_flags_attached list of objects optional Click link for format
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.
patient_status string optional One of "A" (active), "I" (inactive), "D" (inactive-deceased)
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"
referring_doctor object optional
referring_source string optional
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.
updated_at timestamp read-only
workers_comp_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

/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

Filtering parameters:

Key Type Description
date date Only retrieve CCDA data within the given date
date_range date range Only retrieve CCDA data within the given date range

/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/:id/onpatient_access

Retrieve, send or revoke patients' onpatient access.

GET request will return all pending onpatient access invites or active onpatient access, and if you want to send out invite, do a POST request, success response will have status code 204, if you want to revoke a sent invite or an active access, do a DELETE request, success response will have status code 204.

Please note :id parameter in url is ID of the patient.

Required scopes: patients

Required permissions: No special permissions required

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

Supported requests: GET, POST, DELETE

Object key/values:

Key Type Always present Notes
activated_on timestamp Yes When this access is activated
doctor integer Yes
disabled_by integer Yes Id of /api/users
disabled_on timestamp Yes When this access is disabled
enabled_by integer Yes Id of /api/users
enabled_on timestamp Yes When invite of this access is sent out
id integer Yes

/api/patient_flag_types

Retrieve or create patient flag types that belongs to a doctor

Required scopes: patients, settings

Required permissions: Manage Patients, Settings Required

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

Supported requests: GET, POST, PUT, PATCH

Filtering parameters:

Key Type Description
doctor integer List patient flag types for the doctor with the given ID

Object key/values:

Key Type POST/PUT request Notes
archived boolean read-only If the flag type if archived or not
color string optional
created_at timestamp read-only
doctor integer required Doctor who owns the patient flag type
id integer read-only
name string optional Name of the patient flag type
priority integer optional Priority of the patient flag type
updated_at timestamp read-only

/api/patient_messages

Retrieve or create patient messages. If you want to send a message to onpatient, then use this endpoint.

Required scopes: patients, messages

Required permissions: Manage Patients, Access Message Center Required

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

Supported requests: GET, POST, PUT, PATCH

Filtering parameters:

Key Type Description
doctor integer List patient messages for the doctor with the given ID
patient integer List patient messages for the patient with the given ID
since timestamp List patient messages that are updated after the given timestamp

Object key/values:

Key Type POST/PUT request Notes
attachments List of objects optional Please click on link for more information.
body string optional When missing, default to empty string.
created_at timestamp read-only
doctor integer required
id integer read-only
message integer optional ID of /api/messages, the doctor message that is associated with the patient message.
patient integer required The patient this message will be sent to
subject string required Subject of the message is required
updated_at timestamp read-only

/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 If this is not entered, the appointment will be inferred from the 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
notes string optional
patient integer required
payment_transaction_type string optional "" for Credit, "REF" for Refund, "COR" for Correction, "COPAY" for Copay, "COINSR" for Coinsurance, "OTHR" for Other
payment_method string optional "CASH", "CHCK" for Check, "DBIT" for Debit, "CRDT" for Credit Card, "AMEX" for American Express, "VISA", "MSTR" for Mastercard, "DISC" for Discover, "SQR1" for Square (legacy), "SQRE" for Square, "PTPA" for Patient Payments, "ONPT" for onpatient, "OTHR" for Other
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
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.
permissions objects Yes Permissions this user has. Click on link for format.

/api/user_groups

Retrieve user groups in practice group

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
archived boolean Yes Group is archived or not
created_at timestamp Yes
id integer Yes
members array of integer Yes Array of IDs of /api/users
name string Yes
`practice_group integer Yes Practice group this group belongs to
updated_at timestampe Yes

/api/line_items

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

Filtering parameters:

Key Type Description
appointment integer Only retrieve transactions for the appointment with the specified id
doctor integer Only retrieve transactions for the doctor with the specified id
office integer Only retrieve transactions for the office with the specified id
patient integer Only retrieve transactions for the patient with the specified id
service_date date Only retrieve transactions with appointments scheduled within the given date
posted_date date Only retrieve transactions created within given date
since timestamp Only retrieve transactions that have been updated since a given date

Object key/values:

Key Type POST Request Notes
adjustment decimal read-only Adjustment from total billed
appointment integer required Appointment ID
allowed decimal optional Amount allowed by insurance
balance_ins decimal read-only Insurance balance
balance_pt decimal read-only Patient balance
balance_total decimal read-only Total balance
billed decimal optional Total billed
billing_status string read-only 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 Required
denied_flag boolean read-only
diagnosis_pointers list required List of 4 diagnosis pointers, each integers, or ICD code for POST
doctor integer required Doctor ID
id integer read-only
ins1_paid decimal read-only Amount paid by patient's primary insurer
ins2_paid decimal read-only Amount paid by patient's secondary insurer
ins3_paid decimal read-only Amount paid by patient's tertiary insurer
ins_total decimal read-only Amount paid by patient's insurers
insurance_status string read-only This corresponds to the "Status/Adj Type" from billing detail screen
modifiers list optional List of 4 code modifiers, each strings
paid_total decimal read-only Total amount paid
patient integer read-only Patient ID
price decimal required Price of procedure
procedure_type string required One of "CPT(C)", "HCPCS(H)", "Custom(U)", use 1 character identifier when using POST
pt_paid decimal read-only Amount paid by patient
quantity decimal optional
units string read-only Default is 'UN'
posted_date timestamp read-only
updated_at timestamp read-only
service_date date optional Date on which the service was rendered
description string read-only
expected_reimbursement decimal read-only

/api/transactions

Retrieve insurance transactions associated with billing line items(/api/line_items) within 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
appointment integer Only retrieve transactions for the appointment with the specified id
line_item integer Only retrieve transactions for the line item(/api/transactions) with the specified id
posted_date date Only retrieve transactions posted at the specified date
since timestamp Only retrieve transactions updated after the specified timestamp

Object key/values:

Key Type Always Present Notes
adjustment decimal Yes Adjustment from total billed
adjustment_group_code string Yes Group code for adjustment, please see here for more details
adjustment_reason string Yes Reason for adjustment, please see here for more details
appointment integer Yes Appointment ID
check_date date Yes Date of check
claim_status string Yes Status of claim, please see here for more details
created_at datetime Yes
doctor integer Yes
id integer Yes
ins_paid decimal Yes
ins_name integer Yes Can be one of the following 1 - primary insurance, 2 - secondary insurance
line_item integer Yes /api/line_item line item
patient integer Yes
posted_date datetime Yes Date when transaction is created
trace_number string Yes Check number
updated_at datetime Yes

/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
ndc string optional National Drug Codes. It is your responsibility to make sure the codes are correct.
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/procedures

Retrieve procedures for patients owned by 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
appointment integer Only retrieve procedures for the given appointment
doctor integer Only retrieve procedures for the given doctor
patient integer Only retrieve procedures for the patient with the specified id
service_date timestamp Only retrieve procedures for the given date

Object key/values:

Key Type Always present Notes
appointment integer Yes
code string Yes Code related with the procedure
created_at timestamp Yes
date date Yes Service date
description string Yes
doctor integer Yes
id integer Yes
patient integer Yes
procedure_type string Yes One of 'C'(CPT), 'H'(HCPCS), 'U'(Custom) and 'S'(SNOMED)
status string Yes
updated_at timestamp Yes

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

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

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
allowed_values array Yes Value options the field type relies on if applicable, otherwise it will be an empty array
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
comment string No
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

/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, POST, PUT, PATCH

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.
show_persistent boolean This filter parameter should be used along with appointment and clinical_note_template at the same time, to retrieve clinical note field values inherited from persistent templates. Otherwise, it will be ignored.
since timestamp Only retrieve field values updated after the specified timestamp.

Object key/values:

Key Type Always present Description
id integer read only
appointment integer required ID of appointment /api/appointments that the value applies to
clinical_note_field integer required ID of the /api/clinical_note_field_types object that indicates type of the value
value string required Value of the field. Interpretation varies by field type. Please refer to here for more details.
created_at timestamp No
updated_at timestamp No

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

Object 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/inventory_categories

Retrieve diffetent categories of inventories for doctors

Required scopes: clinical

Required permissions: Access Clinical Note

Required account plan: Free trail accounts will not have access

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

Supported requests: GET

Filtering parameters:

Key Type Description
doctor integer Only retrieve inventory categories belongs to the doctor with given ID
since timestamp Only retrieve inventory categories changed after the given timestamp

Object key/values:

Key Type Always present Description
archived boolean Yes If the category is archived or not
category_type string Yes Could be one of vaccine, product or service
created_at timestamp Yes
doctor integer Yes The doctor who owns the category
id integer Yes
name string Yes
updated_at timestamp Yes

/api/inventory_vaccines

Retrieve vaccine inventories for doctors

Required scopes: clinical

Required permissions: Access Clinical Note

Required account plan: Free trail acconuts will not have access

Practice group access: If Share Inventory setting is turned on

Supported requests: GET, POST

Filtering parameters:

Key Type Description
doctor integer Only retrieve inventory vaccines belongs the doctor with given ID
cvx_code string Only retrieve inventory vaccines has matched given cvx codes
status string Only retrieve inventory vaccines has matched given status
since timestamp Only retrieve inventory vaccines changed after the given timestamp

Object key/values:

Key Type POST/PUT requests Description
category integer No Inventory category
cost decimal No Cost of vaccine
`created_at timestamp Read-only
cvx_code string No cvx code of vaccine
current_quantity integer Read-only
doctor integer Yes
expiry date No When will the vaccine expires
id integer Read-only
lot_number string No
manufacturer string No
manufacturer_code string Yes
name string Yes
original_quantity integer No Default to zero
price decimal No
price_with_tax decimal No
sales_tax_applicable boolean No Default to false
status string No Status of vaccine, could be one of active, inactive, archived, voided, default to active
`updated_at timestamp Read-only
vaccination_type string No Default to "standard vaccine"
Note: `current_quantity` field can only be changed by creating new patient vaccine record. Current quantity of an inventory vaccine is calculated by subtract number of records pointing to this inventory from the original quantity value.

/api/patient_vaccine_records

Retrieve or create patient vaccine records

Required scopes: clinical

Required permissions: Access Clinical Note

Required account plan: Free trial accounts will not have access

Practice group access: If Share Inventory setting is turned on

Supported requests: GET, POST, PUT, PATCH

Filtering parameters:

Key Type Description
doctor integer Only retrieve patient vaccine records ordered by doctor with given ID
patient integer Only retrieve patient vaccine records of patient with given ID
cvx_code string Only retrieve patient vaccine records with given cvx code
since timestamp Only retrieve patient vaccine records updated after the given timestamp

Object key/values:

Key Type POST/PUT requests Description
administered_at integer No Office where the administration happens
administered_by integer No User who performs the administration action
administered_start timestamp No Datetime when the administration starts
amount decimal No Amount of vaccine administered
completion_status No Vaccination status, can be CP(Complete), RE(Refused), NA(Not administered), PA(Partially administered)
comments string No
consent_form integer No Consent form related with vaccine record
cpt_code string No Vaccine cpt code
created_at timestamp Read-only
cvx_code string Yes Vaccne cvx code
doses list of integers No Vaccine dose ID received in consent form signed hook
entered_by integer Read-only User who entered this patient vaccine record
funding_eligibility string No The funding program that should pay for a given immunization, options can be found here
id integer Read-only
name string No
next_dose_date date No date for next dose of vaccine
observed_immunity long No Options can be found here
ordering_doctor integer Yes Doctor who ordered the vaccine record
patient integer Yes
record_source string No Options can be found here
route string No Vaccine route, options can be found here
site string No Vaccine site, options can be found here
units string No Unit for vaccine
updated_at timestamp Read-only
vaccine_inventory integer Yes Which inventory this vaccine is from
vis integer Read-only Vaccine information statement related with vaccine
Lab workflow

Here's an example lab order and results submission workflow:

/api/sublabs

Create or retrieve sub-labs (sub-vendors). Please refer to here for an example lab workflow.

Required scopes: labs

Required permissions: No permissions required for reading, for writing, please contact api@drchrono.com

Practice group access: When share_patients is turned on

Supported requests: GET, POST, PATCH, PUT

Object key/value:

Key Type POST/PUT request Description
id integer read-only
name string required
facility_code string required Used for identifying the lab in orders and results

/api/lab_orders

Create or retrieve lab orders. Please refer to here for an example lab workflow.

Required scopes: labs

Required permissions: No permissions required for reading, for writing, please contact api@drchrono.com

Practice group access: When share_patients is turned on

Supported requests: GET, POST, PATCH, PUT

Filtering parameters:

Key Type Description
doctor integer Only retrieve lab orders for the given doctor
since timestamp Only retrieve lab orders created since the given timestamp

Object key/value:

Key Type POST/PUT request Description
id integer read-only
sublab integer required
doctor integer required
patient integer required
documents array of integers read-only IDs of associated /lab_documents objects
timestamp timestamp optional Time at which the order was submitted. Defaults to now
status string optional Equivalent to HL7's ORC.5. See here for values. Defaults to "N".
icd10_codes array of icd10_code optional ICD-10 codes of the conditions which the test concerns. See here for details.
requisition_id string read-only The ID printed on the requisition PDF. Generally the same as id.
accession_number string optional For external use only
notes string optional
priority string optional "NORMAL" or "STAT". Default "NORMAL"

/api/lab_orders_summary

Retrieve summary of lab orders

Required scopes: clinical

Required permissions: Access Clinical Notes

Practice group access: Yes

Supported requests: GET

Filtering parameters:

Key Type Description
doctor integer Only retrieve lab orders ordered by doctor with given ID
patient integer Only retrieve lab orders of patient with given ID
since timestamp Only retrieve lab orders updated after the given timestamp

Object key/value:

Key Type Always present Description
accession_number string Yes
appointment integer Yes
created_at timestamp Yes
doctor integer Yes
id integer Yes
lab string Yes
notes string Yes
origin string Yes
patient integer Yes
priority string Yes Either "N" - "normal", or "S" - "stat"
status string Yes
updated_at timestamp Yes

/api/lab_documents

Create or retrieve lab documents. Please refer to here for an example lab workflow.

Required scopes: labs

Required permissions: No permissions required for reading, for writing, please contact api@drchrono.com

Practice group access: When share_patients is turned on

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

Filtering parameters:

Key Type Description
doctor integer Only retrieve lab orders for the given doctor
since timestamp Only retrieve lab orders created since the given time

Object key/value:

Key Type POST/PUT request Description
id integer read-only
lab_order integer required ID of the order this document is associated with
document file required
type string required See here for values
timestamp timestamp read-only Time at which the document was uploaded

/api/lab_tests

Create or retrieve lab tests. Please refer to here for an example lab workflow.

Required scopes: labs

Required permissions: No permissions required for reading, for writing, please contact api@drchrono.com

Practice group access: When share_patients is turned on

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

Filtering parameters:

Key Type Description
order integer Only retrieve lab tests for given lab order ID(/api/lab_orders).

Object key/value:

Key Type POST/PUT request Description
id integer read only
lab_order integer required ID of the associated lab order
code string optional
name string optional A name for the test
description string optional The short description of the ICD-10 code
collection_date timestamp optional The date the specimen were collected
internal_notes string optional Notes which are meant for, and read by, the labs
report_notes string optional Notes which are not meant for labs, but are copied on the results
status string optional One of preliminary, pending, correction, final, canceled. Defaults to preliminary
specimen_source string optional
specimen_condition string optional
specimen_total_volume float optional

/api/lab_results

Retrieve or create lab results. Please refer to here for an example lab workflow.

Required scopes: labs

Required permissions: No permissions required for reading, for writing, please contact api@drchrono.com

Practice group access: When share_patients is turned on

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

Filtering parameters:

Key Type Description
doctor integer Only retrieve lab results for doctor with given ID
order integer Only retrieve lab results for given lab order ID(/api/lab_orders)

Object key/value:

Key Type POST/PUT request Description
id integer read-only
lab_order integer read-only ID of the /api/lab_orders object the result belongs to.
document integer required ID of the /api/lab_documents object for the result.
lab_test integer required ID of the /api/lab_tests object for the result
specimen_received timestamp required
results_released timestamp required
test_performed timestamp required
status string required See here for allowed values
value string or number required
abnormal_status string optional See here for allowed values
is_abnormal boolean optional If true, the result will be flagged for the doctor's attention
normal_range string optional When value_is_numeric is True, this parameter must be a string of the form "<lower> <upper>", where both lower and upper are numerical
observation_code string optional
observation_description string optional For example, "Blood Urea Nitrogen (BUN)"
group_code string optional This is the code used for grouping result data.
unit string optional Units used for the value
value_is_numeric boolean optional Defaults to False
comments string optional

/api/care_plans

Retrieve care plans of patients

Required scopes: clinical

Required permissions: Access Clinical Notes

Practice group access: When share_patients is turned on

Supported requests: GET

Filtering parameters:

Key Type Description
doctor integer Only retrieve care plans associated with given doctor
patient integer Only retrieve care plans of given patient
plan_type integer Retrieve care plans based on given type

Object key/value:

Key Type Always present Description
appointment integer Yes
code string Yes
code_system string Yes
created_at timestamp Yes
description string Yes
id integer Yes
instructions string Yes
patient integer Yes
plan_type integer Yes Can be one of the following: 1(Goal), 2(Patient education), 3(Patient decision aid), 4(Patient clinical instruction), 5(Referral to other doctor), 6(Health concerns)
scheduled_date date Yes
title string Yes
updated_at timestamp Yes

/api/eligibility_checks

Retrieve past eligibility checks of patients

Required scopes: calendar, patients

Required permissions: Access Scheduling, Manage Patients

Practice group access: When share_patients is turned on

Supported requests: GET

Keys requiring verbose=true: coverage_details (verbose=false will remove empty string fields returned in the response)

Filtering parameters:

Key Type Description
patient integer Only retrieve past eligibility checks for a single patient
appointment integer Only retrieve past eligibility checks run on a specific appointment, which are either run from the 'Eligibility' tab in the appointment pop-up or when a profile is attached to an appointment
appointment_date date Only retrieve past eligibility checks run on appointments that occur on the given date
appointment_date_range date range Only retrieve past eligibility checks run on appointments that occur in the given date range
query_date date Only retrieve past eligibility checks run on a given date
query_date_range date range Only retrieve past eligibility checks run in the given date range
service_types array of strings Only retrieve past eligibility checks for the given service types. See here for a list of valid inputs
eligibilities array of strings Only retrieve past eligibility checks with the given eligibility types. See here for a list of valid inputs

Object key/value:

Key Type Always present Description
patient integer Yes
appointment integer No
cob_level string Yes The level of insurance the eligibility check was run on. Can be one of the following: Primary Insurance or Secondary Insurance
payer_name string No The name of the payer as returned by the clearinghouse that ran the eligibility check
eligibility string Yes See here for a list of possible return values (see description field)
request_service_type string No See here for a list of possible return values (see value field)
service_type_description string No See here for a list of possible return values (see description field)
query_date timestamp No The time at which the request was made
coverage_subscriber object Yes A variable size object containing subscriber information, if returned by the clearinghouse that ran the eligibility check
coverage_details object Yes A variable size object containing the details of the eligibility check, if returned by the clearinghouse that ran the eligibility check

/api/tasks

Retrieve, create or modify tasks of the practice group

Required scopes: tasks

Required permissions: No specific permissions required

Practice group access: Yes

Supported requests: GET, POST, PUT, PATCH

Filtering parameters:

Key Type Description
assignee_user integer Only retrieve tasks assigned to the given user
assignee_group integer Only retrieve tasks assigned to the given user group
status integer Only retrieve tasks with given status
category integer Only retrieve tasks with given category
due_at_date date Only retrieve tasks due at given date
due_at_range date range Only retrieve tasks due within given range
due_at_since timestamp Only retrieve tasks due after given timestamp
due_at_unknown string Value will be evaluated as boolean, if true, only retrieve tasks that do not have due date
since timestamp Only retrieve tasks updated after given timestamp
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 Required POST/PUT Description
archived boolean optional
assigned_by integer read-only ID of /api/users who assigned the task
assignee_user integer optional Either assignee_user or assignee_group should be set
assignee_group integer optional Either assignee_user or assignee_group should be set
associated_items array of objects optional Click link to read more
category integer optional
created_at timestamp read-only
created_by integer read-only ID of /api/users who created the task
due_date object optional Click link to read more
id integer read-only
notes array of objects optional Click link to read more
priority integer optional Can be one of the following 10(Low), 20(Medium), 30(High), 40(Urgent)
status integer required
title string required
updated_at timestamp read-only

/api/task_categories

Retrieve, create or modify task categories

Required scopes: tasks

Required permissions: No specific permission required

Practice group access: Yes

Supported requests: GET, POST, PUT, PATCH

Filtering parameters:

Key Type Description
since timestamp Only retrieve task categories updated after the given timestamp
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 Required POST/PUT Description
archived boolean optional
created_at timestamp read-only
id integer read-only
is_global boolean read-only
name boolean required
practice_group integer read-only
updated_at timestamp read-only

/api/task_notes

Retrieve, create or modify task notes

Required scopes: tasks

Required permissions: No specific permission required

Practice group access: Yes

Supported requests: GET, POST, PUT, PATCH

Filtering parameters:

Key Type Description
task integer Only retrieve task notes that associated with the given task
since timestamp Only retrieve task notes that are updated after the given timestamp

Object key/values:

Key Type Required POST/PUT Description
archived boolean No Is this task note archived or not
created_at timestamp read-only
created_by integer read-only ID of /api/users that created the task note
id integer read-only
task integer Yes Associated /api/tasks item
text string Yes Content of the task note
updated_at timestamp read_only

/api/task_statuses

Retrieve, create or modify task statuses

Required scopes: tasks

Required permissions: No specific permission required

Practice group access: Yes

Supported requests: GET, POST, PUT, PATCH

Filtering parameters:

Key Type Description
since timestamp Only retrieve task status updated after given timestamp
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 Required POST/PUT Description
archived boolean optional
created_at timestamp read-only
id integer read-only
name string required
practice_group integer read-only
status_category string optional Can be one of the following O(open), P(In progress), H(On hold), C(Complete), default to O(Open)
task_category integer optional Id of task category
updated_at timestamp read-only

/api/task_templates

Retrieve, create or modify task templates

Required scopes: tasks

Required permissions: No specific permission required

Practice group access: Yes

Supported requests: GET, POST, PUT, PATCH

Filtering parameters:

Key Type Description
assignee_user integer Only retrieve task templates has given default assignee user
assignee_group integer Only retrieve task templates has given default assignee group
status integer Only retrieve task templates has given default status
category integer Only retrieve task templates has given default category
since timestamp Only retrieve task templates that are updated after given timestamp
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 Required POST/PUT Description
archived boolean optional
created_at timestamp read-only
default_assignee_group integer optional
default_assignee_user integer optional
defatul_category integer optional
default_due_date_offset string optional Offset due date, format should follow "[DD] [HH:[MM:]]ss[.uuuuuu]"
default_note string optional
default_priority integer optional Can be one of the following 10(Low), 20(Medium), 30(High), 40(Urgent)
default_status integer optional
default_title string optional
practice_group integer read-only
name string required
updated_at timestamp read-only

/api/patient_interventions

Retrieve, create or modify patient intervention objects

Required scopes: clinical, patients

Required permissions: Access Clinical Notes, Manage Patients

Practice group access: If share_patients setting is on.

Supported requests: GET, POST, PUT, PATCH

Filtering parameters:

Key Type Description
doctor integer Only retrieve patient intervention objects owned by the given doctor ID
patient integer Only retrieve patient intervention objects of the given patient ID

Object key/values:

Key Type Required POST/PUT Description
code string required Code from different code system
code_system string required Can be SNOMEDCT, HCPCS, CPT, ICD10CM
created_at timestamp read-only
doctor integer required Doctor who owns this intervention object
effective_time timestamp optional
id integer read-only
name string read-only Description of intervention
patient integer required
value_code string optional Code from different code system represent intervention value
value_code_system string optional Can be SNOMEDCT, ICD10CM, LOINC
value_code_name string read-only Description of value

/api/patient_physical_exams

Retrieve, create or modify patient physical exam objects

Required scopes: clinical, patients

Required permissions: Access Clinical Notes, Manage Patients

Practice group access: If share_patients setting is on.

Supported requests: GET, POST, PUT, PATCH

Filtering parameters:

Key Type Description
doctor integer Only retrieve patient physical exam objects owned by the given doctor ID
patient integer Only retrieve patient physical exam objects of the given patient ID

Object key/values:

Key Type Required POST/PUT Description
code string required Code from different code system
code_system string required Can be SNOMEDCT, LOINC
created_at timestamp read-only
doctor integer required Doctor who owns this physical exam object
effective_time timestamp optional
id integer read-only
name string read-only Description of physical exam
patient integer required
value_code string optional Code from different code system represent physical exam value
value_code_system string optional Can be SNOMEDCT, ICD10CM, LOINC
value_code_name string read-only Description of value

/api/patient_risk_assessments

Retrieve, create or modify patient risk assessment objects

Required scopes: clinical, patients

Required permissions: Access Clinical Notes, Manage Patients

Practice group access: If share_patients setting is on.

Supported requests: GET, POST, PUT, PATCH

Filtering parameters:

Key Type Description
doctor integer Only retrieve patient risk assessment objects owned by the given doctor ID
patient integer Only retrieve patient risk assessment objects of the given patient ID

Object key/values:

Key Type Required POST/PUT Description
code string required Code from different code system
code_system string required Can be SNOMEDCT, LOINC
created_at timestamp read-only
doctor integer required Doctor who owns this risk assessment object
effective_time timestamp optional
id integer read-only
name string read-only Description of risk assessment
patient integer required
value_code string optional Code from different code system represent risk assessment value
value_code_system string optional Can be SNOMEDCT, ICD10CM, LOINC
value_code_name string read-only Description of value

/api/patient_communications

Retrieve, create or modify patient communication objects

Required scopes: clinical, patients

Required permissions: Access Clinical Notes, Manage Patients

Practice group access: If share_patients setting is on.

Supported requests: GET, POST, PUT, PATCH

Filtering parameters:

Key Type Description
doctor integer Only retrieve patient communication objects owned by the given doctor ID
patient integer Only retrieve patient communication objects of the given patient ID

Object key/values:

Key Type Required POST/PUT Description
code string required Code from different code system
code_system string required Can be SNOMEDCT
created_at timestamp read-only
doctor integer required Doctor who owns this communication object
effective_time timestamp optional
id integer read-only
name string read-only Description of communication
patient integer required
value_code string optional Code from different code system represent communication value
value_code_system string optional Can be SNOMEDCT, ICD10CM, LOINC
value_code_name string read-only Description of value

/api/implantable_devices

Retrieve implantable devices of patients

Required scopes: clinical

Required permissions: Access Clinical Notes

Practice group access: If share_patients setting is on.

Supported requests: GET

Filtering parameters:

Key Type Description
doctor integer Only retrieve implantable devices from procedures operated by the given doctor ID
patient integer Only retrieve implantable devices of the given patient ID

Object key/values:

Key Type Always Present Description
archived bollean Yes
brand_name string Yes
company_name string Yes
created_at timstamp Yes
expiration_date date Yes
gmdn_pt_name string Yes "GMDN PT Name" or "SNOMED CT Description" mapped to the attribute in the "GMDN PT Name"
id integer Yes
manufacturing_date date Yes
patient integer Yes
procedure integer Yes Id of /api/procedures
serial_number string Yes
status string Yes One of 'active' or 'inactive'
udi string Yes
updated_at timestamp Yes
version_or_model string Yes

/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. POST request does not expect any payload. 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 patient 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, along with a parameter called msg.

Please use your webhook's secret token as hash key and SHA-256 as digest constructor, hash the msg value with HMAC algorithm. And we expect a 200 JSON response, in JSON response body, there should be a key called secret_token existing, and its value should be equal to the hashed msg. Otherwise, verification would fail.

Here is an example webhook verification in Python:

import hashlib, hmac

def webhook_verify(request):
    secret_token = hmac.new(WEBHOOK_SECRET_TOKEN, request.GET['msg'], hashlib.sha256).hexdigest()
    return json_response({
        'secret_token': secret_token
    })
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.

Free API Development Terms and Conditions