logo
API docs by Redocly

Cerbo API Documentation (1.0.0)

Download OpenAPI specification:Download

E-mail: support@cer.bo URL: https://cer.bo/ License: Proprietary Terms of Service

Overview

This API documentation is intended for developers who want to integrate with Cerbo's REST API.

Best Practices

As with any development project that involves sensitive data, follow best security practices and ensure the most efficient ways to retrieve specific data. The sections below are not comprehensive, but they are a good starting point.

General

  • The API should only be enabled if you have an active application that needs to be connected. Do not request credentials until you're ready to start working with the API.
  • API credentials are NOT the same as user credentials. You cannot use API credentials to log into the user interface of the EHR and vice versa.
  • Requested API uses should only have the minimum necessary permissions required to perform the actions you expect to need them for. Common permission restrictions include:
    • Read-only access to resources.
    • Enforcing an anonymize flag for applications which are doing general data analysis to remove most identifying properties about patients.
    • Restricting access to resources.

Security

  • API credentials should be stored and transmitted securely. At no point should API credentials be stored outside of a secure environment and they should be shared only with parties that require them.
  • Any technical support questions should not include credential data as part of the support ticket.
  • If your application server has a static IP address, you may request that the API connection is only accessible via that IP address.
  • API credentials are intended only for server-side use. They should never be used in client-side applications.
  • The API uses BASIC authentication, which can be formatted as a base64-encoded username:password string. Do not assume that encoded credentials are any safer than plain-text credentials.
  • If you are using a username:password@api-subdomain formatted URL to write API curl commands rather than header-based authentication, ensure that you are not logging the raw commands in any way.
  • For web-based applications, ensure that credentials are stored in a way that they cannot be compromised in the event of a breach.
  • Ensure that error reporting on the application does not potentially output debugging information that might expose credentials.
  • Ensure that only authorized users have access to the source-code of your application and API credentials.
  • If you suspect that API credentials might have been exposed immediately disable the API user through the Cerbo interface and request new credentials be issued.
  • Data passing through the API is generally sensitive - ensure that your environment is secure and meets regulatory requirements.
  • If using the anonymize flag in your application, do not assume that the consuming application will not be able to identify the patient. API data responses contain a large number of data-points that could be used in conjunction to identify a patient, and questionnaire data included in responses are not scrubbed in any way (these questions are custom for each client, so Cerbo does not know which questions might be identifying).
  • Disable any API users as soon as they are no longer in use.

Performance

  • When testing or developing an application, please request a sandbox environment to test your application before deploying it in production.
  • When synchronizing large amounts of data, use the delta endpoint to calculate which resources have been added, removed, and/or modified within a time-period rather than re-sycning large numbers of documents/data that may already be cached.
  • Avoid PATCH commands where no data is being updated where possible.
  • Avoid multi-threaded requests where possible. You'll risk putting too much load on your database and you may also trigger a rate-limit lock (specific rate limits are different by endpoint, and single-threaded requests will almost never trigger a lock other than for credential validation endpoints or endpoints that trigger emails to be sent).
  • When possible, for high-volume data-transfers (downloading large amounts of data), these should be scheduled for off-peak hours (after 5PM Pacific, before 8AM Eastern).
  • Only use the extended_details endpoint (which returns a huge amount of data per patient) if you need most of the included data - almost all the data returned by that endpoint is available via more targeted endpoints which will generally be much faster.

Webhooks

The REST API serves as an excellent way for your application to request specific data or to initiate changes to data in Cerbo. However, there are many scenarios where your application needs notifications about events in the EHR. These types of notifications are called webhooks and Cerbo allows you to easily configure these notices for many actions so your application will be notified when these specific events are triggered within the EHR.

Webhooks can be configured under the Admin > Manage > Integrations flyout menus. Only users with Superadmin permissions are able to update webhooks. When you add a webhook endpoint, you must enter the URL and select each event for which you would like to receive notifications.

Some important notes about webhooks and their limitations:

  • In order for your application to receive webhooks you must set up a callback URL that is accessible via the HTTPS protocol using a fully qualified domain name. The HTTPS protocol requirement ensures that data will remain secure in transit to your application, but it means that you must have a valid SSL certificate set up on your application server.
  • Webhooks contain PHI - please ensure that you have adequate security set up around your listening application and hosting environment, and that you're taking precautions when logging and storing incoming webhooks.
  • For security purposes you may want to add authorization headers to your webhooks. Our interface allows you to specify these headers, and we recommend doing this to avoid having malicious actors send fake webhook data to your application. Our webhooks do not create a sending hash that uniquely verifies each outbound webhook message, so please make sure to keep these authorization headers safe.
  • If you want additional security on your webhooks, you can also choose to whitelist the IP address of your Cerbo server.
  • Webhooks are sent in real time. When a change is made in Cerbo, if there is a configured webhook for that action then a notification will be sent immediately.
  • We do not re-transmit webhooks that do not result in 200 response codes from the receiving application. This means that if your application is offline or having issues, you will not receive webhooks triggered during the outage period.
  • The JSON data that is included is often more limited than what you would see from API responses. We recommend that most webhooks be responded to by an API call to fetch the expanded object. This will ensure data integrity.
  • Cerbo offers a delta API endpoint that performs a similar function to webhooks, and can be very useful for cases where triggers are not time-sensitive, but webhooks are generally the easiest way to get notified of changes that occur within Cerbo.

Appointments

Get all appointments

Get all appointments for a specified date range

Authorizations:
basic_auth
query Parameters
start_date
required
string
Example: start_date=2020-01-01

Starting date of the date range. The start date should be formatted as YYYY-MM-DD.

end_date
required
string
Example: end_date=2020-02-01

Ending date of the date range. The end date should be formatted as YYYY-MM-DD.

provider_id
integer
Example: provider_id=1

Provider identifier. If specified, results will be for only that provider.

pt_id
integer
Example: pt_id=1

Patient identifier. If specified, results will be for only that patient.

include_cancelled
boolean
Example: include_cancelled=y

If specified and not empty, results will include cancelled appointments.

include_work_schedule
boolean
Example: include_work_schedule=y

Include details about when a provider is set to work.

status
Array of strings

Appointment status. If specified, results will be for only the given statuses. Valid statuses include scheduled, confirmed, checked-in, in-room, cancelled. Clinic custom statuses may also be used.

limit
integer <= 1000
Default: 1000

Limit of how many records to return. Often used in conjunction with offset for pagination.

offset
integer

Offset of where to start the returned records. Often used in conjunction with limit for pagination.

Responses

Request samples 

curl -X GET \
https://un:pwd@subdomain.md-hq.com/api/v1/appointments?limit=10&start_date=2017-01-01&end_date=2017-12-31&provider_id=7&status=confirmed

Response samples

Content type
application/json
{
  • "object": "list",
  • "total_count": 0,
  • "has_more": true,
  • "data": [
    ]
}

Create a new appointment

Create a new appointment

Authorizations:
basic_auth
Request Body schema: application/json
start_date_time
required
string

Starting datetime of the date range. This field should be formatted as YYYY-MM-DD HH:MM.

end_date_time
required
string

Ending datetime of the date range. This field should be formatted as YYYY-MM-DD HH:MM.

provider_ids
required
Array of integers

An array of provider identifiers associated with this appointment.

pt_id
integer

A patient identifier associated with this appointment.

appointment_type
required
string

Valid appointment type name.

title
required
string

Display title of the appointment.

appointment_note
required
string

Accompanying notes for the appointment.

status
string
Default: "scheduled"

The status of the appointment. Valid statuses include scheduled, confirmed, checked-in, in-room, cancelled. Clinic custom statuses may also be used.

telemedicine
boolean
Default: false

Flag for whether or not this is a telemedicine appointment.

Responses

Request samples

Content type
application/json
{
  • "start_date_time": "2020-01-01 09:00",
  • "end_date_time": "2020-02-01 09:30",
  • "provider_ids": [
    ],
  • "pt_id": 1,
  • "appointment_type": "Preventative Care",
  • "title": "string",
  • "appointment_note": "string",
  • "status": "scheduled",
  • "telemedicine": false
}

Get an appointment

Get an appointment

Authorizations:
basic_auth
path Parameters
appointment_id
required
integer

Appointment identifier.

Responses

Update an appointment

Update an appointment

Authorizations:
basic_auth
path Parameters
appointment_id
required
integer

Appointment identifier.

Request Body schema: application/json
start_date_time
string

Starting datetime of the date range. This field should be formatted as YYYY-MM-DD HH:MM.

end_date_time
string

Ending datetime of the date range. This field should be formatted as YYYY-MM-DD HH:MM.

provider_ids
Array of integers

An array of provider identifiers associated with this appointment.

pt_id
integer

A patient identifier associated with this appointment.

appointment_type
string

Valid appointment type name.

title
string

Display title of the appointment.

appointment_note
string

Accompanying notes for the appointment.

status
string

The status of the appointment. Valid statuses include scheduled, confirmed, checked-in, in-room, cancelled. Clinic custom statuses may also be used.

Responses

Request samples

Content type
application/json
{
  • "start_date_time": "2020-01-01 09:00",
  • "end_date_time": "2020-02-01 09:30",
  • "provider_ids": [
    ],
  • "pt_id": 1,
  • "appointment_type": "Preventative Care",
  • "title": "string",
  • "appointment_note": "string",
  • "status": "string"
}

Destroy an appointment

Destroy an appointment. This method should be used to completely remove an appointment. If you are looking to cancel an appointment, instead use the update endpoint and set the status to cancelled.

Authorizations:
basic_auth
path Parameters
appointment_id
required
integer

Appointment identifier.

Responses

Request samples 

curl -X DELETE https://un:pwd@subdomain.md-hq.com/api/v1/appointments/542

Appointment Types

Get all appointment types

Get all appointment types If the email_reminder_hrs_before or sms_reminder_hrs_before values are less than zero, it means that they inherit the timing from the default practice settings.

Authorizations:
basic_auth
query Parameters
include_deleted
boolean
Example: include_deleted=y

If specified and not empty, results will include deleted appointment types.

limit
integer <= 1000
Default: 1000

Limit of how many records to return. Often used in conjunction with offset for pagination.

offset
integer

Offset of where to start the returned records. Often used in conjunction with limit for pagination.

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/appointment_types

Response samples

Content type
application/json
{
  • "object": "list",
  • "total_count": 0,
  • "has_more": true,
  • "data": [
    ]
}

Charges

Get Charge Definitions

Get All Charge Definitions from the Master Ledger

Authorizations:
basic_auth
query Parameters
limit
integer <= 100
Default: 100
offset
integer

If the returned data indicates that there is more than the limit responses (has_more: true), then it will offset the list to allow you to cycle through charge definitions.

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/charge_master?limit=10&offset=0

Response samples

Content type
application/json
{
  • "object": "list",
  • "total_count": 0,
  • "has_more": true,
  • "data": [
    ]
}

Get Single Charge Definition

Get Single Charge Definition from the Master Ledger

Authorizations:
basic_auth
path Parameters
charge_id
required
integer

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/charge_master/2

Response samples

Content type
application/json
{
  • "object": "charge_definition",
  • "id": "string",
  • "name": "string",
  • "name_for_pt_portal": "string",
  • "category": "string",
  • "cpt_code": "string",
  • "nicknames": [
    ],
  • "barcode_upc": "string",
  • "description": "string",
  • "retail": "string",
  • "wholesale": "string",
  • "is_supply": true,
  • "time_required": "string",
  • "is_taxable": true,
  • "tax_rate": "string",
  • "is_special": true,
  • "add_to_insurance_claims": true,
  • "inactive": true,
  • "addedby": "string",
  • "created": "string"
}

Get Patient Charges

Get All Patient Charges

path Parameters
pt_id
required
integer

The ID of the patient.

query Parameters
limit
integer

The maximum number of charges to return (default is 100).

offset
integer

Offset the list to allow cycling through patient charges.

date_method
string

If you're filtering by date range, should the range be calculated by date the charge was created, or the recorded transaction date? Valid arguments are 'created' and 'transaction' (created is the default).

start_date
string

Show charges from after this date (calculated by date_method).

end_date
string

Show charges from before this date (calculated by date_method).

Responses

Request samples 

curl -X GET "https://un:pwd@subdomain.md-hq.com/api/v1/patients/2/charges?limit=100&offset=0&start_date=2018-10-01&end_date=2018-10-31"

Response samples

Content type
application/json
{
  • "object": "list",
  • "total_count": 0,
  • "has_more": true,
  • "data": [
    ]
}

Get Charges from Encounter

Get All Charges from a Single Encounter

path Parameters
pt_id
required
integer

The ID of the patient.

encounter_id
required
integer

The ID of the encounter.

query Parameters
limit
integer

The maximum number of charge definitions to return (default is 100).

offset
integer

Offset the list to allow cycling through charge definitions.

Responses

Request samples 

curl -X GET "https://un:pwd@subdomain.md-hq.com/api/v1/patients/2/encounters/423/charges"

Response samples

Content type
application/json
{
  • "object": "list",
  • "description": "encounter_charges",
  • "total_count": 0,
  • "has_more": true,
  • "data": [
    ]
}

Deltas

Get all differences

Get all differences of resources in a specified date time range

Authorizations:
basic_auth
path Parameters
resource_type
required
string

Resource type. Valid resources include appointments, rxs, pt_rx, drugs, supplements, orders, pt_orders, documents, patients, users, tags, pt_tags, tasks.

query Parameters
start_date
required
string
Example: start_date=2020-01-01

Starting date of the date range. The start date should be formatted as YYYY-MM-DD. The start date can also include time, and should be formatted as YYYY-MM-DD HH:MM:SS.

end_date
required
string
Example: end_date=2020-02-01

Ending date of the date range. The end date should be formatted as YYYY-MM-DD. The end date can also include time, and should be formatted as YYYY-MM-DD HH:MM:SS. The end date must be later than the start date, but can NOT be longer than a week in length.

Responses

Request samples 

curl -X GET "https://un:pwd@subdomain.md-hq/api/v1/delta/documents?start_date=2020-01-20&end_date=2020-01-22"

Response samples

Content type
application/json
{
  • "object": "delta",
  • "resource_type": "documents",
  • "from_date": "string",
  • "until_date": "string",
  • "delta_data": {
    }
}

Drugs

Search for drugs by term

Please note: All dates listed are listed in UTC, so you’ll want to adjust for your local timezone. These endpoints allow to you search/get details about specific medications. If you are looking for API calls on patient-specific prescriptions as opposed to drug definitions, please use the Patient Prescriptions endpoint. Also, these drug definitions are licensed data from Wolters Kluwer and your usage of these endpoints are limited to functions that you can perform in the EMR or patient portal. You may not use this drug data for purposes other than management of medications for your Cerbo patient population. You can enter several terms with spaces between each (make sure to url-encode the search string, so spaces would be %20). Each term is treated as potentially a wildcard search so tylen%203 (tylen 3) would return Tylenol 325mg, Tylenol Syrup 30mg, etc.

path Parameters
limit
integer <= 100
Default: 50

Limit number of results

offset
integer

Offset the results

favorites-only
boolean
Default: true

Return only drugs from provider's favorites list

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/drugs/search/tylenol

Get a single drug

path Parameters
drug_id
integer

ID of drug

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/drugs/2

Encounters

Get All Encounters for a Patient

Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC, so you'll want to adjust for your local timezone. The returned JSON will include prescribed medications, supplements, recommendations (and other alternate plan items), diagnoses. One thing to note: the API is designed to return attachments (documents and images that are included in the encounter) with the response, but currently this functionality is disabled and an empty array will always be returned.

path Parameters
patient_id
required
integer

The ID of the patient.

query Parameters
limit
integer

The maximum number of encounters to return (default is 100).

offset
integer

Offset the list to allow cycling through encounter notes.

type
string

Limit results to a specific encounter note type (e.g., "ov" for office visit).

signed_only
boolean

If included and set to "false," return all encounter notes, including those not marked as signed.

Responses

Request samples 

curl -X GET "https://un:pwd@subdomain.md-hq.com/api/v1/patients/2/encounters?limit=10&signed_only=false&type=ov"

Get a single encounter's details

Get a single encounter's details

path Parameters
encounter_id
required
integer

The ID of the encounter note.

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/encounters/231

Delete an Encounter

Authorizations:
basic_auth
path Parameters
id
required
integer

Encounter identifier.

Responses

Request samples 

curl -X DELETE https://un:pwd@subdomain.md-hq.com/api/v1/encounters/1

Response samples

Content type
application/json
{
  • "result": true,
  • "object": "encounter",
  • "id": 0,
  • "data": null,
  • "action": "removed",
  • "message": "Encounter successfully deleted"
}

Create a New Encounter on a Patient Chart

Request Body schema: application/json
required
pt_id
integer

A valid ID of a non-archived patient.

date_of_service
string <date>

A time stamp (YYYY-MM-DD format preferred) representing the date the encounter took or will take place. Can be future or past.

title
string

The title of the encounter note.

content
string

The plaintext-formatted text of the encounter note.

encounter_type
string

The two-letter abbreviation of the type of encounter note you are creating.

owner
integer

A valid ID of a non-archived, non-resource user who is the expected owner/manager of the note. Default is the API “user” itself.

parent_encounter
integer

The valid ID of an existing encounter for the designated patient. If set, the new note will be filed as a sub-note of the designated parent encounter. The parent note must belong to the patient set by pt_id and it must not be a sub-note itself.

Responses

Request samples

Content type
application/json
{
  • "pt_id": 0,
  • "date_of_service": "2019-08-24",
  • "title": "string",
  • "content": "string",
  • "encounter_type": "string",
  • "owner": 0,
  • "parent_encounter": 0
}

Extended Patient Details

Get all patients with extended (research) details

Most data about an individual patient is available through specific calls for patient documents, demographics, vitals, etc. However, for research purposes you often want to pull a large amount of discrete data about patients, so Cerbo provides a specific endpoint that aggregates most relevant data into a single call.

To access your patient's extended data, first run an API call to return all patients, then loop through the patient ids returned in that response and fetch each patient's extended details.

Please note: All dates listed are listed in UTC, so you'll want to adjust for your local timezone. Also, the API responses include some routes that may not be available for your instance.

Also note: The responses for this call can often be large (more than 1MB/patient in some scenarios) so response times to this call can vary. Please rate-limit this call to 20 calls/second and we recommend waiting until after business hours if you are going to run this for all patients.

For a full sample response, please visit https://demo1.md-hq.com/custom/sample_data/extended_details.json

Authorizations:
basic_auth
path Parameters
id
integer

The ID of the patient.

query Parameters
anonymize
bool

The return values will strip PHI identifiers from the chart including: names, street-level addresses, telephone numbers (area codes will remain), date-of-birth (year of birth will remain) and some questionnaire answers. Because ever client has different questionnaires, you will want to make sure you further anonymize the results if your questionnaires include requests for identifying information

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com /api/v1/patients/2/extended_details?anonymize=true

Health Maintenance

Get all Health Maintenance Trackers

Get all Health Maintenance Trackers from the Master Health Maintenance List.

Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for your local timezone.

query Parameters
limit
integer

Defaults to 100, but can be overridden (max is 100).

offset
integer

If the returned data indicates that there is more than the limit responses (has_more: true), then it will offset the list to allow you to cycle through long health maintenance tracker object lists.

include_specific_pt
boolean

If set, returns specific patient data.

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/health_maintenance?limit=10&offset=0&include_specific_pt=1

Get single Health Maintenance Tracker

Get single Health Maintenance Tracker from the Master Health Maintenance List

path Parameters
health_maintenance_id
required
integer

The ID of the health maintenance tracker to retrieve.

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/health_maintenance/2

Response samples

Content type
application/json
{
  • "object": "health_maintenance_tracker",
  • "id": "2",
  • "name": "Annual Exam",
  • "description": "",
  • "sex": "Both",
  • "start_age": 0,
  • "end_age": 200,
  • "frequency": "12 months",
  • "applies_to": "All Patients",
  • "overrides": null,
  • "icd_codes": "",
  • "created": "2019-03-30 02:01:34",
  • "addedby": "18"
}

Facilities

Get all Laboratory definitions

Get all Laboratory definitions from the Master Laboratories List.

Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for your local timezone.

query Parameters
city
string

Returns laboratory listings defined as being in this city.

state
string

Returns laboratory listings defined as being in this state.

company-brand
string

Returns laboratory listings of this brand (e.g., "Quest").

limit
integer

Upper bound on number of returned laboratory listings

offset
integer

Lower bound on number of returned laboratory listings

Responses

Request samples 

curl -X GET "https://un:pwd@subdomain.md-hq.com/api/v1/laboratories?limit=10&offset=0&city=Portland"

Partner Applications

Get all electronically-submitted orders to Quest Diagnostics for a patient

Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC, so you'll want to adjust for your local timezone.

path Parameters
patient_id
integer

ID of patient who orders apply to

query Parameters
limit
integer

Defaults to 100, but can be overridden (max is 100).

offset
integer

If the returned data indicates that there is more than the limit responses (has_more: true), then it will offset the list to allow you to cycle through long health maintenance tracker object lists.

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/partners/quest/orders

Get a single electronically-submitted order to Quest Diagnostics by the Quest order ID

path Parameters
order_id
integer

ID of order to show

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/partners/quest/orders/2

Get the raw requisition document for an electronically-submitted order to Quest Diagnostics by the requisition ID

path Parameters
order_id
integer

ID of order to show

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/partners/quest/requisition/3/content

Patient Charges

Get all estimated charges for a patient

path Parameters
pt_id
integer
query Parameters
limit
integer

defaults to 100, but can be overridden (max is 100).

offset
integer

If the returned data indicates that there is more than the limit responses (has_more: true), then it will offset the list to allow you to cycle through patient estimated charges.

date_method
string
Enum: "created" "transaction"

If you're filtering by date range, should the range be calculated by date the estimated charge was created, or the recorded transaction date (manual date assigned to the estimated charge)? Valid arguments are created and transaction (created is the default).

start_date
string <date>

If this argument is included it will only show estimated charges from after this date (calculated by date_method).

end_date
string <date>

If this argument is included it will only show estimated charges from before this date (calculated by date_method).

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/2/estimates?limit=100&offset=0&start_date=2024-01-01&end_date=2024-01-31

Response samples

Content type
application/json
{
  • "object": "list",
  • "description": "patient_estimates",
  • "total_count": 0,
  • "has_more": true,
  • "data": [
    ]
}

Get all estimated charges for a patient from a single encounter

path Parameters
pt_id
integer
encounter_id
integer
query Parameters
limit
integer

defaults to 100, but can be overridden (max is 100).

offset
integer

If the returned data indicates that there is more than the limit responses (has_more: true), then it will offset the list to allow you to cycle through patient estimated charges.

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/2/encounters/423/estimates

Response samples

Content type
application/json
{
  • "object": "list",
  • "description": "encounter_estimates",
  • "total_count": 0,
  • "has_more": true,
  • "data": [
    ]
}

Get a specific patient estimated charge by ID

path Parameters
pt_id
integer
estimate_id
integer

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/2/estimates/64

Response samples

Content type
applicatin/json
{
  • "object": "patient_estimate",
  • "id": 0,
  • "name": "string",
  • "patient_id": 0,
  • "encounter_id": 0,
  • "amount": "string",
  • "quantity": 0,
  • "discount_multiplier": 0,
  • "charge_master_details": {
    },
  • "billing_rules": {
    },
  • "location_identifier": "string",
  • "additional_details": "string",
  • "notes": "string",
  • "owner_id": 0,
  • "addedby": 0,
  • "created": "string",
  • "transaction_date": "2019-08-24",
  • "payment_details": "string",
  • "is_deleted": true,
  • "date_deleted": "2019-08-24",
  • "expiration_date": "2019-08-24",
  • "converted_tp_patient_charge_id": "string"
}

Patient Documents

Get All Documents for a Patient

Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC, so you'll want to adjust for your local timezone.

path Parameters
patient_id
integer

ID of patient

query Parameters
limit
integer

(optional) defaults to 100, but can be overridden (max is 100)

offset
integer

(optional) If the returned data indicates that there are more responses than the limit (has_more: true), then it will offset the list to allow you to cycle through documents.

folder
string

(optional) String (folder name). Limits results to a specific folder or "tab."

Responses

Request samples 

curl -X GET "https://un:pwd@subdomain.md-hq.com/api/v1/patients/2/documents"

Add a document via the portal queue

path Parameters
patient_id
integer

ID of patient

query Parameters
enqueue
bool

(true by default) If true, the system will insert the document into the active patient portal queue so that the clinic is notified and can review the proposed addition

Request Body schema: application/json
required
pt_id
integer

(required) An integer identifier for the patient associated with the document.

mime_type
string

(required) A string indicating the MIME type of the file. Valid MIME types are listed above.

name
string

(required) A string to be used as the title of the document.

base64_content
string <binary>

(required) Binary data, encoded base64. Maximum file size is 16MB.

notes
string

(optional) A string

Responses

Request samples

Content type
application/json
{
  • "pt_id": 0,
  • "mime_type": "string",
  • "name": "string",
  • "base64_content": "string",
  • "notes": "string"
}

Get a single document by document ID

path Parameters
document_id
integer

ID of document

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/documents/4225

Get the binary or raw file data by document ID

path Parameters
document_id
integer

ID of document

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/documents/1337/content

Stream the binary or raw file data by document ID

path Parameters
document_id
integer

ID of document

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/documents/1337/stream

Patients

Get all patients

Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC, so you'll want to adjust for your local timezone.

query Parameters
limit
integer

(optional) defaults to 100, but can be overridden (max is 100)

offset
integer

If the returned data indicates that there is more than the limit responses (has_more: true), then it will offset the list to allow you to cycle through long patient list

status
boolean

If this parameter is set it will only include ACTIVE patients

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com /api/v1/patients

Create a new patient

Data: property-value key-pairs, including nested objects for address and insurance information (match the structure from the GET API call)

Notes: At a minimum, you must provide a first name, last name, date of birth (preferred format is YYYY-MM-DD), and sex (must be M, F, or ?)

Request Body schema: application/json
required
first_name
required
integer
last_name
required
string

(required) A string indicating the MIME type of the file. Valid MIME types are listed above.

dob
required
string

YYYY-MM-DD

sex
required
string

must be 'M', 'F', or '?'

Responses

Request samples

Content type
application/json
{
  • "first_name": 0,
  • "last_name": "string",
  • "dob": "string",
  • "sex": "string"
}

Get a single patient (by ID)

path Parameters
patient_id
integer

ID of patient

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/2

Update a patient

Data: property-value key-pairs, including nested objects for address and insurance information (match the structure from the GET API call)

Request Body schema: application/json
required
first_name
integer
last_name
string

(required) A string indicating the MIME type of the file. Valid MIME types are listed above.

dob
string

YYYY-MM-DD

sex
string

must be 'M', 'F', or '?'

Responses

Request samples

Content type
application/json
{
  • "first_name": 0,
  • "last_name": "string",
  • "dob": "string",
  • "sex": "string"
}

Archive a patient

path Parameters
patient_id
integer

ID of patient

Responses

Request samples 

curl -X DELETE https://un:pwd@subdomain.md-hq.com/api/v1/patients/316

Find all patients matching criteria

query Parameters
limit
integer

(optional) defaults to 100, but can be overridden (max is 100)

offset
integer

If the returned data indicates that there is more than the limit responses (has_more: true), then it will offset the list to allow you to cycle through long patient list

last_name
string

(optional) Match patients with given last name. Allows wildcard: smith% will match “Smith”,”Smithson”,”Simthe” etc)

first_name
string

(optional) Match patients with given first name Allows wildcard: ben% will match “Ben”,”Benjamin”,”Bennett” etc)

email
string

(optional) Match patients with given email as their primary or secondary address Allows wildcard: %@gmail.com will match all patients with Gmail addresses

username
string

(optional) Match patients with given patient portal username

dob
string

(optional) Match patients with given date of birth (preferred format is yyyy-mmdd). No wildcards allowed

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/search?first_name=John%&last_name=Doe%&dob=1980-12-01

Patient Emails

Send an email to a patient's primary email address

This endpoint allows you to send an email in the same format as other system-generated emails (with your logo at the top and practice information at the bottom). This will look identical to emails sent to patients by clicking on their email address from the Patient Information block in the EMR.

Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC, so you'll want to adjust for your local timezone.

Request Body schema: application/json
subject
required
string

Subject of email to be sent

body
required
string

Body of email to be sent

reply-to
required
string

This is the address that any patient response will be forwarded to (the email itself will be sent from do-not-reply@md-hq.com).

Responses

Request samples

Content type
application/json
{
  • "subject": "string",
  • "body": "string",
  • "reply-to": "string"
}

Patient facilities

Get all laboratories for a patient

Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for your local timezone.

path Parameters
patient_id
required
integer

ID of patient

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/laboratories

Add a preferred laboratory for a patient

path Parameters
patient_id
required
integer

ID of patient

Request Body schema: application/json
required
laboratory_id
required
integer

An integer, the laboratory ID to add. See the "Facility Endpoints" documentation for how to find the ID in the master laboratories database

priority_order
integer

An integer representing where in the patient's laboratories list this entry should go (lowest number is considered the first/preferred listing). If null, the system will look at set_as_primary instead.

set_as_primary
boolean

A boolean value representing if this should be added as the patient's new preferred listing, or just added to the bottom of the list. If priority_order is set, this argument will be ignored.

note
string

A string, 255 character max

Responses

Request samples

Content type
application/json
{
  • "laboratory_id": 0,
  • "priority_order": 0,
  • "set_as_primary": true,
  • "note": "string"
}

Delete patient laboratory

path Parameters
patient_id
required
integer

ID of patient

patient_laboratory_id
required
integer

ID of patient laboratory entry

Responses

Request samples 

curl -X DELETE https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/laboratories/22

Patient Free-Text Notes

Get all available patient free-text note types

Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for your local timezone.

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/pt_notes

Get all free-text notes for a patient

path Parameters
patient_id
integer

ID of patient

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/pt_notes

Get free-text notes of one type for a patient

path Parameters
patient_id
integer

ID of patient

pt_note_type_id
integer

ID of note type

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/pt_notes/1

Edit a specific free-text note for a patient

path Parameters
patient_id
integer

ID of patient

pt_note_type_id
integer

ID of note type

Request Body schema: application/json
required
note
required
string

The new free-text note value

Responses

Request samples

Content type
application/json
{
  • "note": "string"
}

Patient Images

Get all images for a patient

Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for your local timezone.

query Parameters
limit
integer

Defaults to 100, but can be overridden (max is 100).

offset
integer

If the returned data indicates that there are more responses than the limit (has_more: true), then it will offset the list to allow you to cycle through documents.

photo_type
string

String (either “personal” or “medical”). If left blank, both types will be returned.

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/images?photo_type=personal

Add a patient personal image via the portal queue

path Parameters
patient_id
integer

ID of patient

Request Body schema: application/json
required
pt_id
required
integer

An integer identifier for the patient associated with the document.

mime_type
required
string

A string indicating the MIME type of the file.

Valid MIME types: image/jpeg image/jpg image/gif image/png image/pngx

base64_content
required
string <binary>

Binary data, encoded base64. Maximum file size is 16MB.

Responses

Request samples

Content type
application/json
{
  • "pt_id": 0,
  • "mime_type": "string",
  • "base64_content": "string"
}

Get a single patient image by image ID

path Parameters
patient_id
integer

ID of patient

image_id
integer

ID of image

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/images/54

Get the binary or raw file data by image ID

path Parameters
patient_id
integer

ID of patient

image_id
integer

ID of image

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/images/54/content

Stream the binary or raw file data by image ID

path Parameters
patient_id
integer

ID of patient

image_id
integer

ID of image

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/images/54/stream

Patient Health Maintenance

Get all health maintenance readings for a patient

Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for your local timezone.

path Parameters
patient_id
integer

ID of patient

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/health_maintenance

Add a health maintenance reading for a patient

path Parameters
patient_id
required
integer

ID of patient

health_maintenance_id
required
integer

ID of health maintenance entry

*See “HEALTH MAINTENANCE ENDPOINTS” documentation to get definitions from the master health maintenance trackers list

Request Body schema: application/json
required
date
required
string

A string specifying the date of the health maintenance tracker.

notes
integer

A string

Responses

Request samples

Content type
application/json
{
  • "date": "string",
  • "notes": 0
}

Patient Invoices

Get All Invoices for a Patient

Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for your local timezone.

path Parameters
patient_id
integer

ID of patient

query Parameters
limit
integer

Defaults to 100, but can be overridden (max is 100).

offset
integer

If the returned data indicates that there are more responses than the limit (has_more: true), then it will offset the list to allow you to cycle through invoices.

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/2/invoices?limit=10

Get a single invoice by invoice ID

path Parameters
invoice_id
integer

ID of invoice

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/invoices/4225

Patient Orders

Get All Orders for a Patient

Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for your local timezone.

path Parameters
patient_id
integer

ID of patient

Responses

Request samples 

curl -X GET "https://un:pwd@subdomain.md-hq.com/api/v1/patients/2/orders"

Get a single order by order ID

path Parameters
patient_id
integer

ID of patient

order_id
integer

ID of patient

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1//patients/343/orders/1462

Patient Past Medical History

Get the Past Medical History for a patient

Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for your local timezone.

path Parameters
patient_id
integer

ID of patient

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/pmh

Response samples

Content type
application/json
{
  • "object": "list",
  • "total_count": 0,
  • "data": [
    ]
}

Patient Portal

Get all enqueued portal requests for a patient

Please note: All dates listed are listed in UTC, so you'll want to adjust for your local timezone. Also, the API responses include some routes that may not be available for your instance. For the most part adding to the patient portal is going to be made through message-type specific endpoints (i.e. the /patients/:pt_id/questionnairesendpoint or the/patients/:pt_id/rxs endpoint) and the documentation for those posts are listed alongside other related calls. However, if you're just looking to summarize or manage posts that are already in queue (before they've been dismissed) you can use the calls below:

path Parameters
pt_id
integer

ID of patient

query Parameters
request_type
string

(COMING SOON) return only specific types of requests

status
string

(COMING SOON) return requests of a specific status (defaults to “open”)

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/portal/enqueued

Delete/remove an enqueued request

All API-supported DELETE commands are “soft-deletes” so the data remains available but hidden. The time and API-user-identifier are both recorded automatically

path Parameters
pt_id
integer

ID of patient

queue_request_id
integer

ID of queued request

Responses

Request samples 

curl -X DELETE https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/portal/enqueued/27

Trigger an email invitation to join portal (or reset password)

This will try to send an email to the patient's primary email address with an encrypted link. The text and subject of this email will be the same as the settings that you use when inviting patients from inside the EMR.

path Parameters
pt_id
integer

ID of patient

Responses

Request samples 

curl -X POST https://ben:password@sandbox.md-hq.com/api/v1/patients/221/portal/invite

Validate patient portal login credentials

If the credentials are valid, this will return the matching patient's details

Request Body schema: application/json
required
username
required
string

The patient's username that they use to login to your patient portal

password
required
string

The patient's password that they use to login to your patient portal

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "result": true,
  • "message": "string",
  • "patient_details": {
    }
}

Patient Prescriptions

Get All Prescriptions for a Patient

Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC, so you'll want to adjust for your local timezone. If you want to manage underlying drug definitions please use the /v1/drugs endpoints.

path Parameters
patient_id
integer

ID of patient

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/2/rxs

Post a new patient prescription via the portal queue

path Parameters
patient_id
integer

ID of patient

query Parameters
enqueue
boolean

(true by default) If true, the system will insert the drug into the active patient portal queue so that the clinic is notified and can review the proposed addition. This replicates the functionality of the patient portal queue.

Request Body schema: application/json
required
drug_id
required
integer

An integer identifier for a drug as returned from a /v1/drugs/search/:term query.

notes
string

Responses

Request samples

Content type
application/json
{
  • "drug_id": 0,
  • "notes": "string"
}

Get a Single Patient Prescription Details

path Parameters
patient_id
integer

ID of patient

medication_prescribed_id
integer

ID of prescribed medication

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/rxs/4225

Post a medication prescription refill via the portal queue

path Parameters
patient_id
integer

ID of patient

Request Body schema: application/json
required
original_prescription_id
required
integer

An integer identifier for an existing prescription for this patient as returned from a /v1/patients/:patient_id/rxs GET query.

notes
string
agreed_to_terms
string

A string value representing agreement to terms. If not set, defaults to "No terms agreed to".

Responses

Request samples

Content type
application/json
{
  • "original_prescription_id": 0,
  • "notes": "string",
  • "agreed_to_terms": "string"
}

Patient Subscriptions

Get All Subscriptions

Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for your local timezone.

query Parameters
limit
integer

Number of results returned. Default (and maximum) is 100.

offset
integer

Used for looping through the dataset. Default is 0.

include_deleted
boolean

Returns deleted and current subscriptions if set to true. Default is false.

schedule_frequency
string
Enum: "monthly" "weekly" "annually"

If set to monthly/weekly/annually, it will only return subscriptions billing at that frequency.

subscription_charge_id
string

ID of a specific charge associated with a subscription-type. If set, it will only return that type of subscription.

charge_owner_user_id
string

ID of a Cerbo user that gets 'credit' for that subscription. If set, it will only return 'their' subscriptions.

Responses

Request samples 

curl -X GET https://pk_username:sk_password@subdomain.md-hq.com/api/v1/patients/subscriptions?include_deleted=true&limit=5&schedule_frequency=monthly&subscription_charge_id=1021

Get All Subscriptions for a Single Patient

path Parameters
patient_id
integer

ID of patient

query Parameters
include_deleted
boolean

False by default. Returns deleted and current subscriptions if set to true.

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1540/subscriptions?include_deleted=true

Patient Supplements

Get All Supplements for a Patient

Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC, so you'll want to adjust for your local timezone. If you want to manage underlying supplement definitions please use the /v1/ supplements endpoints.

path Parameters
patient_id
integer

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/2/supplements

Post a new patient supplement via the portal queue

path Parameters
patient_id
integer
query Parameters
enqueue
boolean

(true by default) If true, the system will insert the supplement into the active patient portal queue so that the clinic is notified and can review the proposed addition. This replicates the functionality of the patient portal queue.

Request Body schema: application/json
required
supplement_id
required
integer

An integer identifier for a supplement as returned from a /v1/supplements/search/:term query.

notes
string

Responses

Request samples

Content type
application/json
{
  • "supplement_id": 0,
  • "notes": "string"
}

Get a single patient supplement details

path Parameters
patient_id
integer
supplement_prescribed_id
integer

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/supplements/325

Users

Get all users

Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC, so you’ll want to adjust for your local timezone. These endpoints allow you to query the system about users (providers and other staff) in Cerbo.

query Parameters
limit
integer

Defaults to 10, but can be overridden (max is 100)

offset
integer

If the returned data indicates that there is more than the limit responses (has_more: true), then it will offset the list to allow you to cycle through users.

status
string

If a non-empty value is passed the system will include deleted/suspended users in the return. If the argument is omitted only active users will be returned.

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com /api/v1/users?limit=10

Get a single user's details

query Parameters
id
integer

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/users/11

Validate user credentials

This endpoint is rate limited to 3 attempts per 10 seconds, and 120 per 12-hour period.

Request Body schema: application/json
required
user
required
string

username

password
required
string

Responses

Request samples

Content type
application/json
{
  • "user": "string",
  • "password": "string"
}

Patient Tags

Get all tags for a patient

Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for your local timezone.

path Parameters
patient_id
integer

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/tags

Response samples

Content type
application/json
{
  • "object": "list",
  • "total_count": 0,
  • "has_more": true,
  • "data": {
    }
}

Add or edit tags for a patient

path Parameters
patient_id
integer
Request Body schema: application/json
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "tags": [
    ]
}

Delete patient tag

path Parameters
patient_id
integer
tag_name
string <urlencoded>

Responses

Request samples 

curl -X DELETE https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/tags/New%20Patient

Patient Vaccines

Get all vaccine records for a patient

Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC, so you'll want to adjust for your local timezone. If you want to manage underlying supplement definitions please use the /v1/ supplements endpoints.

path Parameters
patient_id
integer

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/vaccines

Response samples

Content type
application/json
{
  • "object": "list",
  • "total_count": 0,
  • "has_more": true,
  • "data": {
    }
}

Patient Vitals

Get all height readings for a patient

Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for your local timezone.

path Parameters
patient_id
integer

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/vitals/height

Response samples

Content type
application/json
{
  • "object": "list",
  • "total_count": 0,
  • "has_more": true,
  • "data": [
    ]
}

Add a height reading for a patient

path Parameters
patient_id
integer
Request Body schema: application/json
required
height
string

A string specifying the height reading

units
string

A string specifying the unit (inches or “cm”)

comments
string
date_taken
string

A string specifying the date and time of the vital reading (if no valid 3-letter timezone specified, defaults to UTC). If left blank, defaults to the current time.

Responses

Request samples

Content type
application/json
{
  • "height": "string",
  • "units": "string",
  • "comments": "string",
  • "date_taken": "string"
}

Get all weight readings for a patient

path Parameters
patient_id
integer

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/vitals/weight

Response samples

Content type
application/json
{
  • "object": "list",
  • "total_count": 0,
  • "has_more": true,
  • "data": [
    ]
}

Add a weight reading for a patient

path Parameters
patient_id
integer
Request Body schema: application/json
required
weight
string

A string specifying the weight reading

units
string

A string specifying the unit (“lbs” or “kg”)

comments
string
date_taken
string

A string specifying the date and time of the vital reading (if no valid 3-letter timezone specified, defaults to UTC). If left blank, defaults to the current time.

Responses

Request samples

Content type
application/json
{
  • "weight": "string",
  • "units": "string",
  • "comments": "string",
  • "date_taken": "string"
}

Get all blood pressure readings for a patient

path Parameters
patient_id
integer

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/vitals/bp

Response samples

Content type
application/json
{
  • "object": "list",
  • "total_count": 0,
  • "has_more": true,
  • "data": [
    ]
}

Add a blood pressure reading for a patient

path Parameters
patient_id
integer
Request Body schema: application/json
required
systolic
string

A string specifying the systolic pressure reading

diastolic
string

A string specifying the diastolic pressure reading

pulse
string

A string specifying the pulse (b/min) reading

comments
string
date_taken
string

A string specifying the date and time of the vital reading (if no valid 3-letter timezone specified, defaults to UTC). If left blank, defaults to the current time.

Responses

Request samples

Content type
application/json
{
  • "systolic": "string",
  • "diastolic": "string",
  • "pulse": "string",
  • "comments": "string",
  • "date_taken": "string"
}

Get all readings of a custom vital type for a patient

path Parameters
patient_id
integer

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/vitals/weight

Response samples

Content type
application/json
{
  • "object": "list",
  • "total_count": 0,
  • "has_more": true,
  • "data": [
    ]
}

Add a custom vital reading for a patient

path Parameters
patient_id
integer
vital_id
integer
Request Body schema: application/json
required
string or boolean

A string or boolean value for the vital reading, depending on the custom vital type.

abnormal
boolean

A boolean value to indicate if the reading should be marked as abnormal. If left blank, defaults to false (the vital reading is added as “normal”)

comments
string
date_taken
string

A string specifying the date and time of the vital reading (if no valid 3-letter timezone specified, defaults to UTC). If left blank, defaults to the current time.

Responses

Request samples

Content type
application/json
{
  • "value": "string",
  • "abnormal": true,
  • "comments": "string",
  • "date_taken": "string"
}

Questionnaires

Get All Questionnaires for a Patient

Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC, so you'll want to adjust for your local timezone.

path Parameters
patient_id
integer
query Parameters
extended_details
boolean

Defaults to false, but can be overridden. If false (good for looping through lots of questionnaires) it will not return the actual key-value responses that the patient submitted and instead return a NULL value for the raw_data property.

Responses

Request samples 

curl -X GET "https://un:pwd@subdomain.md-hq.com/api/v1/patients/2/questionnaires?ßextended_details=true"

Post a new Questionnaire

Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC, so you'll want to adjust for your local timezone.

path Parameters
patient_id
integer
Request Body schema: application/json
required
questionnaire_type
string
questionnaire_name
string
html_content
required
string <html>

An HTML-formatted string that will serve as the human-readable version of the patient responses

required
object

An object with key-value pairs that will represent the structured data underlying the patient responses. This allows us to analyze their response-data.

Responses

Request samples

Content type
application/json
{
  • "questionnaire_type": "string",
  • "questionnaire_name": "string",
  • "html_content": "string",
  • "raw_data": {
    }
}

Get a Single Questionnaire’s Details

path Parameters
patient_id
integer
questionnaire_id
integer
query Parameters
extended_details
boolean

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/questionnaires/25?extended_details=true

Secure Messages

Get all secure messages for a patient

Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for your local timezone.

path Parameters
patient_id
integer
query Parameters
sent_by
string

Either “pt” (to get all messages sent by the patient) or “dr” (to get all messages sent to the patient from doctor/clinic)

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/1/portal/secure_messages?sent_by=pt

Post a new secure message via the portal queue (patient → provider)

path Parameters
patient_id
integer
Request Body schema: application/json
required
subject
required
string

between 1 and 54 characters long

note
required
string

at least 10 characters long

dr_id
integer

A valid ID of a non-archived, non-resource user who should respond to the message

reply
string
Enum: "secure message" "phone" "other" "none"

how the patient would like to receive a response

Responses

Request samples

Content type
application/json
{
  • "subject": "string",
  • "note": "string",
  • "dr_id": 0,
  • "reply": "secure message"
}

Response samples

Content type
application/json
{
  • "result": true,
  • "message": "string",
  • "portal_queue_id": 0
}

Supplements

Get all supplements

Please note: All dates listed are listed in UTC, so you’ll want to adjust for your local timezone. Also, the API responses include some routes that may not be available for your instance. Supplements can also be accessed through the /alternate_plans/ endpoints, but because most clinics handle supplements separately you will want to use the /supplements/ endpoints unless you’re actively managing other products. Also, these endpoints pertain only to supplement definitions - if you’re looking for patient-associated prescriptions for supplements (including prescribing details) please use the /patients/:pt_id/supplements endpoints.

Also note that while you have full usage rights over any supplement that was created/defined by your practice, and data sets that were installed or provided by a third party are subject to usage restrictions

query Parameters
limit
integer

Defaults to 100, but can be overridden (max is 100)

offset
integer

If the returned data indicates that there is more than the limit responses (has_more: true), then it will offset the list to allow you to cycle through long supplement list

active_only
boolean

If this parameter is set it will only include ACTIVE supplements

vendor_code
string

If this parameter is set it will only supplements with matching vendor code (note, this is different from the external_ref_id).

class
string

If this parameter is set it will only supplements with that class specified

external_ref_id
string

If this parameter is set it will only include items with the designated external identifier - generally you will want to make this unique so it only includes a single item.

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/supplements?limit=10&class=sampleClass

Create a new supplement

Request Body schema: application/json
required

At a minimum, you must provide a name, and the name must be unique (it will throw an error if there is a duplicate note)

name
required
string
nicknames
string
vendor_code
string
description
string
external_ref_id
string
inactive
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "nicknames": "string",
  • "vendor_code": "string",
  • "description": "string",
  • "external_ref_id": "string",
  • "inactive": true
}

Search all supplements

path Parameters
terms
string <urlencoded>

You can enter several terms with spaces between each (make sure to url-encode the search string, so spaces would be %20). Each term is treated as potentially a wildcard search so “vitam%20D” (“vitam D”) would return “Vitamin D”, “Vitamin D1000”, etc.

query Parameters
limit
integer

Defaults to 100, but can be overridden (max is 100)

offset
integer

If the returned data indicates that there is more than the limit responses (has_more: true), then it will offset the list to allow you to cycle through long supplement list

active_only
boolean

If this parameter is set it will only include ACTIVE supplements

vendor_code
string

If this parameter is set it will only supplements with matching vendor code (note, this is different from the external_ref_id).

class
string

If this parameter is set it will only supplements with that class specified

external_ref_id
string

If this parameter is set it will only include items with the designated external identifier - generally you will want to make this unique so it only includes a single item.

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/supplements/search/vitam%20d?limit=10&class=sampleClass

Get a single supplement

path Parameters
supplement_id
integer

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/supplements/2

Update a supplement

path Parameters
supplement_id
integer
Request Body schema: application/json
required

Any value which is provided will update, so do not add empty fields to the patch data unless you want these fields to be set to empty.

name
string
nicknames
string
vendor_code
string
description
string
external_ref_id
string
inactive
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "nicknames": "string",
  • "vendor_code": "string",
  • "description": "string",
  • "external_ref_id": "string",
  • "inactive": true
}

Tags

Get All Tag Definitions from the Master Tag List

Please note: All dates listed (creation times, update-times) are listed in UTC, so you’ll want to adjust for your local timezone. Please also note that this set of endpoints is for managing the master tag list - if you’re looking to see how to grab patients with specific tags or how to apply tags to patients, please see the /patients endpoints.

query Parameters
include_deleted
boolean

Defaults to false, but any non-empty value will include deleted tags in the returned array

Responses

Request samples 

curl -X GET "https://un:pwd@subdomain.md-hq.com/api/v1/tags"

Tasks

Get all tasks

Please note: All dates listed (creation times, due dates, reminder dates) are listed in UTC, so you’ll want to adjust for your local timezone.

query Parameters
limit
integer

Defaults to 100, but can be overridden (max is 100)

offset
integer

If the returned data indicates that there is more than the limit responses (has_more: true), then it will offset the list to allow you to cycle through a long task list

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/tasks

Response samples

Content type
application/json
{
  • "object": "list",
  • "search-filters": { },
  • "total_count": 0,
  • "has_more": null,
  • "data": [
    ]
}

Post a new task

Please note: All dates listed (creation times, due dates, reminder dates) are listed in UTC, so you’ll want to adjust for your local timezone.

Request Body schema: application/json
required
dr_id
required
integer

A valid ID of a non-archived, non-resource user who the task is being added for.

subject
required
string
priority
required
string
Enum: "low" "normal" "high"
notes
string
pt_id
integer

A valid ID of a non-archived patient to associate with the task.

due_date
string <date-time>

A time stamp (YYYY-MM-DD HH:MM:SS format) representing the due date for this task.

remind_minutes_before
integer

Represents the number of minutes before your due date to remind the user of the task (due_date must be set).

Responses

Request samples

Content type
application/json
{
  • "dr_id": 0,
  • "subject": "string",
  • "priority": "low",
  • "notes": "string",
  • "pt_id": 0,
  • "due_date": "2019-08-24T14:15:22Z",
  • "remind_minutes_before": 0
}

Get a single task

path Parameters
task_id
integer

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/tasks

Response samples

Content type
application/json
{
  • "object": "task",
  • "id": 0,
  • "dr_id": 0,
  • "subject": "string",
  • "start_date": "string",
  • "due_date": "string",
  • "reminder_time": "string",
  • "notes": "string",
  • "priority": "low",
  • "addedby": 0,
  • "patient_details": {
    },
  • "completed_on": "string",
  • "associated_resource_type": "string",
  • "associated_resource_id": 0,
  • "created": "string"
}

Update an existing task

path Parameters
task_id
integer
Request Body schema: application/json
required
dr_id
required
integer

A valid ID of a non-archived, non-resource user who the task is being added for.

subject
required
string
priority
required
string
Enum: "low" "normal" "high"
notes
string
pt_id
integer

A valid ID of a non-archived patient to associate with the task.

due_date
string <date-time>

A time stamp (YYYY-MM-DD HH:MM:SS format) representing the due date for this task.

remind_minutes_before
integer

Represents the number of minutes before your due date to remind the user of the task (due_date must be set).

Responses

Request samples

Content type
application/json
{
  • "dr_id": 0,
  • "subject": "string",
  • "priority": "low",
  • "notes": "string",
  • "pt_id": 0,
  • "due_date": "2019-08-24T14:15:22Z",
  • "remind_minutes_before": 0
}

Vitals

Get all Custom Vital definitions from the Master Vitals List

Please note: All dates listed (creation times, date taken) are listed in UTC, so you’ll want to adjust for your local timezone.

query Parameters
show_all
boolean

If set to “true”, returns the entire custom vitals list, otherwise only returns the items configured to appear on patient charts

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/vitals?limit=10&offset=0&show_all=true

Get single Custom Vital definition from the Master Vitals List

path Parameters
vital_id
integer

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/vitals/114

Response samples

Content type
application/json
{
  • "object": "vital_definition",
  • "id": 0,
  • "name": "Glucose",
  • "name_full": "Blood Glucose",
  • "nicknames": "string",
  • "units": "mg/dL",
  • "unit_type": "Numeric",
  • "notes": "string",
  • "normal_low": "string",
  • "normal_high": "string",
  • "dashboard_active": true,
  • "addedby": 0,
  • "created": "2019-08-24T14:15:22Z"
}

Patient Lab Results

Get all lab results for a patient

Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for your local timezone.

path Parameters
patient_id
integer

ID of patient

Responses

Request samples 

curl -X GET https://un:pwd@subdomain.md-hq.com/api/v1/patients/2/lab_results

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}