{ "openapi": "3.1.0", "info": { "version": "1.0.0", "title": "Cerbo API Documentation", "license": { "name": "Proprietary", "identifier": "proprietary" }, "termsOfService": "https://www.cer.bo/end-user-license-agreement", "contact": { "email": "support@cer.bo", "url": "https://www.cer.bo/" }, "x-logo": { "url": "https://cdn.prod.website-files.com/65d66824dcf38868709865d1/65d8d903832f5ed26ca29567_logo.svg" }, "description": "# Overview\nThis API documentation is intended for developers who want to integrate with Cerbo's REST API.\n\n# Best Practices\nAs 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.\n\n## General\n- Use of the API is subject to Cerbo's [MSA](https://www.cer.bo/master-subscription-agreement) and [EULA](https://www.cer.bo/end-user-license-agreement).\n- 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.\n- 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.\n- 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:\n - Read-only access to resources.\n - Enforcing an `anonymize` flag for applications which are doing general data analysis to remove most identifying properties about patients.\n - Restricting access to resources.\n\n## Security\n- 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.\n- Any **technical support questions should not include credential data** as part of the support ticket.\n- If your application server has a static IP address, you may request that the API connection is only accessible via that IP address.\n- API credentials are intended **only for server-side use**. They should never be used in client-side applications.\n- The API uses BASIC authentication. Credentials should be a base64-encoded `username:password` string sent in an `Authorization` header. Do not assume that encoded credentials are any safer than plain-text credentials.\n - `Authorization: Basic CREDS`, where **CREDS** is the base64-encoded credentials.\n- For web-based applications, ensure that credentials are stored in a way that they cannot be compromised in the event of a breach.\n- Ensure that error reporting on the application does not potentially output debugging information that might expose credentials.\n- Ensure that only authorized users have access to the source-code of your application and API credentials.\n- **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.\n- Data passing through the API is generally sensitive - ensure that your environment is secure and meets regulatory requirements.\n- 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).\n- Disable any API users as soon as they are no longer in use.\n\n## Performance\n- When testing or developing an application, please request a sandbox environment to test your application before deploying it in production.\n- 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.\n- Avoid `PATCH` commands where no data is being updated where possible.\n- 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).\n- 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).\n- 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.\n\n# Webhooks\nThe 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.\n\nWebhooks 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.\n\nSome important notes about webhooks and their limitations:\n- 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.\n- 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.\n- 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.\n- If you want additional security on your webhooks, you can also choose to _whitelist_ the IP address of your Cerbo server.\n- 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.\n- 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.\n- 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.\n- Cerbo offers a [delta API endpoint](#tag/Deltas) 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.\n\n# Use-Cases and Examples\n\n- [Creating Insurance ADT or DFT HL7 Messages from Cerbo's API](https://cerbo.zendesk.com/hc/en-us/articles/38984006496795-Creating-Insurance-ADT-or-DFT-HL7-Messages-from-Cerbo-s-API)\n" }, "servers": [ { "url": "https://{tenant}.md-hq.com/api/v1", "variables": { "tenant": { "default": "clinic-subdomain", "description": "Your clinic subdomain" } } } ], "security": [ { "basic_auth": [] } ], "tags": [ { "name": "Appointments", "description": "Operations for appointments" }, { "name": "Appointment Availability", "description": "Operations for appointment availability" }, { "name": "Appointment Reminders", "description": "Operations for appointment reminders" }, { "name": "Appointment Types", "description": "Operations for appointment types" }, { "name": "Charges", "description": "Operations for charges" }, { "name": "Deltas", "description": "Operations for differences" }, { "name": "Drugs", "description": "Operations for drugs and medications" }, { "name": "Encounter Types", "description": "Operations for encounter types" }, { "name": "Encounters", "description": "Operations for encounter notes" }, { "name": "Extended Patient Details", "description": "Get patient extended details" }, { "name": "Facilities", "description": "Operations for labs/facilities" }, { "name": "Health Maintenance", "description": "Operations for health maintenance" }, { "name": "Inventory", "description": "Operations for inventory management" }, { "name": "Partner Applications", "description": "Operations for third party partner applications" }, { "name": "Patients", "description": "Operations for patients" }, { "name": "Patient Allergies", "description": "Operations for patient allergies" }, { "name": "Patient Charges", "description": "Operations for patient estimated charges" }, { "name": "Patient Documents", "description": "Operations for patient documents" }, { "name": "Patient Emails", "description": "Operations for patient emails" }, { "name": "Patient Facilities/Specialists", "description": "Operations for managing patient associations with laboratories, pharmacies, and specialists (preferred provider management)" }, { "name": "Patient Free-Text Notes", "description": "Operations for patient free-text notes" }, { "name": "Patient Health Maintenance", "description": "Operations for patient health maintenance entries" }, { "name": "Patient Images", "description": "Operations for patient images" }, { "name": "Patient Invoices", "description": "Operations for patient invoices" }, { "name": "Patient Orders", "description": "Operations for patient orders" }, { "name": "Patient Past Medical History", "description": "Operations for patient PMH entries" }, { "name": "Patient Portal", "description": "Operations for patient portal" }, { "name": "Patient Prescriptions", "description": "Operations for patient prescriptions" }, { "name": "Patient Subscriptions", "description": "Operations for patient subscriptions" }, { "name": "Patient Supplements", "description": "Operations for patient supplements" }, { "name": "Patient Tags", "description": "Operations for patient tags" }, { "name": "Patient Vaccines", "description": "Operations for patient vaccines" }, { "name": "Patient Vitals", "description": "Operations for patient vitals" }, { "name": "Questionnaires", "description": "Operations for questionnaires" }, { "name": "Secure Messages", "description": "Operations for secure messages" }, { "name": "Supplements", "description": "Operations for supplements" }, { "name": "Tags", "description": "Operations for tags" }, { "name": "Tasks", "description": "Operations for tasks" }, { "name": "Users", "description": "Operations for users" }, { "name": "Vitals", "description": "Operations for custom vitals" } ], "paths": { "/appointments": { "get": { "operationId": "listAppointments", "tags": [ "Appointments" ], "summary": "Get all appointments", "description": "Get all appointments for a specified date range", "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "start_date", "in": "query", "description": "Starting date of the date range. The start date should be formatted as `YYYY-MM-DD`.", "required": true, "example": "2020-01-01", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "description": "Ending date of the date range. The end date should be formatted as `YYYY-MM-DD`.", "required": true, "example": "2020-02-01", "schema": { "type": "string" } }, { "name": "provider_id", "in": "query", "description": "Provider identifier. If specified, results will be for only that provider.", "required": false, "example": 1, "schema": { "type": "integer" } }, { "name": "pt_id", "in": "query", "description": "Patient identifier. If specified, results will be for only that patient.", "required": false, "example": 1, "schema": { "type": "integer" } }, { "name": "include_cancelled", "in": "query", "description": "If specified and not empty, results will include cancelled appointments. Any non-empty value is treated as true.", "required": false, "example": "y", "schema": { "type": "string" } }, { "name": "include_work_schedule", "in": "query", "description": "Include details about when a provider is set to work. Any non-empty value is treated as true.", "required": false, "example": "y", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Appointment status. If specified, results will be for only the given statuses.\nValid statuses include `scheduled`, `confirmed`, `checked-in`, `in-room`, `cancelled`.\nClinic custom statuses may also be used.\n", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "in": "query", "description": "Limit of how many records to return.\nOften used in conjunction with offset for pagination.\n", "required": false, "schema": { "type": "integer", "default": 1000, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Offset of where to start the returned records.\nOften used in conjunction with limit for pagination.\n", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "appointment" ] }, "id": { "type": "integer" }, "title": { "type": "string" }, "appointment_status": { "type": "string" }, "appointment_location": { "type": "string" }, "recurrance_interval": { "type": "integer" }, "recurrance_type": { "type": [ "string", "null" ] }, "recurrance_value": { "type": [ "string", "null" ] }, "recurrance_group": { "type": [ "string", "null" ] }, "addedby": { "type": "integer" }, "datedeleted": { "type": [ "string", "null" ], "format": "datetime" }, "patient_details": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "patient" ] }, "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "middle_name": { "type": "string" }, "dob": { "type": "string", "format": "date" }, "sex": { "type": "string", "enum": [ "M", "F" ] }, "email1": { "type": "string" }, "url_patient_details": { "type": "string" } } }, "associated_providers": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "integer" }, "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "prefix": { "type": "string" }, "suffix": { "type": "string" }, "npi": { "type": "string" }, "email": { "type": "string" }, "is_resource": { "type": "boolean" }, "associated_by": { "type": "integer" }, "date_associated": { "type": "string", "format": "datetime" }, "is_active_user": { "type": "boolean" }, "url_user_details": { "type": "string" } } } }, "telemedicine": { "type": "object", "properties": { "is_telemedicine": { "type": "boolean" }, "telemedicine_url": { "type": [ "string", "null" ] } } }, "start_date_time": { "type": "string", "format": "datetime" }, "end_date_time": { "type": "string", "format": "datetime" }, "appointment_type": { "type": "string" }, "appointment_note": { "type": "string" }, "created": { "type": "string", "format": "datetime" } } } } } } } } }, "400": { "description": "Unauthorized" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET \\\nhttps://subdomain.md-hq.com/api/v1/appointments?limit=10&start_date=2017-01-01&end_date=2017-12-31&provider_id=7&status=confirmed\n" } ] }, "post": { "operationId": "createAppointment", "tags": [ "Appointments" ], "summary": "Create a new appointment", "description": "Create a new appointment", "security": [ { "basic_auth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "start_date_time": { "type": "string", "description": "Starting datetime of the date range.\nThis field should be formatted as `YYYY-MM-DD HH:MM`.\n", "example": "2020-01-01 09:00" }, "end_date_time": { "type": "string", "description": "Ending datetime of the date range.\nThis field should be formatted as `YYYY-MM-DD HH:MM`.\n", "example": "2020-02-01 09:30" }, "provider_ids": { "type": "array", "items": { "type": "integer" }, "description": "An array of provider identifiers associated with this appointment.", "example": [ 1 ] }, "pt_id": { "type": "integer", "description": "A patient identifier associated with this appointment.", "example": 1 }, "appointment_type": { "type": "string", "description": "Valid appointment type `name`.", "example": "Preventative Care" }, "title": { "type": "string", "description": "Display title of the appointment." }, "appointment_note": { "type": "string", "description": "Accompanying notes for the appointment." }, "status": { "description": "The status of the appointment.\nValid statuses include `scheduled`, `confirmed`, `checked-in`, `in-room`, `cancelled`.\nClinic custom statuses may also be used.\n", "type": "string", "default": "scheduled" }, "telemedicine": { "type": "boolean", "default": false, "description": "Flag for whether or not this is a telemedicine appointment." } }, "required": [ "start_date_time", "end_date_time", "provider_ids", "appointment_type", "title", "appointment_note" ] } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Unauthorized" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"start_date_time\":\"2018-08-11 14:30\",\"end_date_time\":\"2018-08-11 15:00\",\"provider_ids\":[8,14],\"pt_id\":2,\"title\":\"Initial Visit\",\"appointment_note\":\"John has been having headaches\",\"appointment_type\":\"Office Visit\"}' -X POST https://subdomain.md-hq.com/api/v1/appointments\n" } ] } }, "/appointments/availability": { "get": { "operationId": "getAppointmentAvailability", "tags": [ "Appointment Availability" ], "summary": "Get appointment availability", "description": "Get appointment availability for providers and/or appointment types.\n", "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "start_date", "in": "query", "description": "Starting date of the date range. The start date should be formatted as `YYYY-MM-DD`.", "required": true, "example": "2020-01-01", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "description": "Ending date of the date range. The end date should be formatted as `YYYY-MM-DD`. The end date cannot be more than 90 days from the start date.", "required": true, "example": "2020-02-01", "schema": { "type": "string" } }, { "name": "provider_ids", "in": "query", "description": "Provider identifiers. If specified, results will be for only those providers.", "required": false, "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "appointment_type_ids", "in": "query", "description": "Appointment type identifiers. If specified, results will be for only those appointment types.", "required": false, "schema": { "type": "array", "items": { "type": "integer" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "parameters": { "type": "object", "properties": { "start_date": { "type": "string" }, "end_date": { "type": "string" }, "provider_ids": { "type": "array", "items": { "type": "integer" } }, "appointment_type_ids": { "type": "array", "items": { "type": "integer" } } } }, "gmt_timezone_offset": { "type": "string" }, "has_more": { "type": "boolean" }, "user_availabilies": { "type": "array", "items": { "type": "object", "properties": { "provider_id": { "type": "integer" }, "provider_details": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "integer" }, "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "prefix": { "type": "string" }, "suffix": { "type": "string" }, "npi": { "type": "string" }, "email": { "type": "string" }, "is_resource": { "type": "boolean" }, "has_calendar": { "type": "boolean" }, "user_notes": { "type": "string" }, "login_active": { "type": "boolean" }, "active": { "type": "boolean" }, "display_name_for_messages": { "type": "string" }, "display_name_for_appointments": { "type": "string" }, "created": { "type": "string" } } }, "availability_by_type": { "type": "array", "items": { "type": "object", "properties": { "appointment_type_id": { "type": "integer" }, "appointment_type_details": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "name_portal": { "type": "string" }, "color_hex": { "type": "string" }, "description": { "type": "string" }, "allow_on_portal": { "type": "boolean" }, "number_of_overlaps_to_allow": { "type": "integer" }, "portal_notice": { "type": "string" }, "which_providers": { "type": "array", "items": { "type": "integer" } }, "default_length": { "type": "integer" }, "default_status": { "type": "string" }, "sort_order": { "type": "integer" }, "telemedicine": { "type": "boolean" }, "is_active": { "type": "boolean" }, "inactive_date": { "type": "string" }, "created": { "type": "string" }, "created_by": { "type": "integer" } } }, "available_windows": { "type": "array", "items": { "type": "object", "properties": { "window_start": { "type": "string" }, "window_end": { "type": "string" }, "minutes_available_at_this_time": { "type": "integer" } } } } } } } } } } } } } } }, "400": { "description": "Unauthorized" }, "500": { "description": "Error\nReference the `error.message` value for more details.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "argument_error", "unspecified_error" ] }, "message": { "type": "string" } } } } } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/appointments/availability?start_date=2024-09-01&end_date=2024-10-01&provider_ids[]=473&appointment_type_ids[]=8&appointment_type_ids[]=341\n" } ] } }, "/appointments/{appointment_id}": { "get": { "operationId": "showAppointment", "tags": [ "Appointments" ], "summary": "Get an appointment", "description": "Get an appointment", "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "appointment_id", "in": "path", "description": "Appointment identifier.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Unauthorized" } } }, "patch": { "operationId": "updateAppointment", "tags": [ "Appointments" ], "summary": "Update an appointment", "description": "Update an appointment", "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "appointment_id", "in": "path", "description": "Appointment identifier.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Unauthorized" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "start_date_time": { "type": "string", "description": "Starting datetime of the date range.\nThis field should be formatted as `YYYY-MM-DD HH:MM`.\n", "example": "2020-01-01 09:00" }, "end_date_time": { "type": "string", "description": "Ending datetime of the date range.\nThis field should be formatted as `YYYY-MM-DD HH:MM`.\n", "example": "2020-02-01 09:30" }, "provider_ids": { "type": "array", "items": { "type": "integer" }, "description": "An array of provider identifiers associated with this appointment.", "example": [ 1 ] }, "pt_id": { "type": "integer", "description": "A patient identifier associated with this appointment.", "example": 1 }, "appointment_type": { "type": "string", "description": "Valid appointment type `name`.", "example": "Preventative Care" }, "title": { "type": "string", "description": "Display title of the appointment." }, "appointment_note": { "type": "string", "description": "Accompanying notes for the appointment." }, "status": { "description": "The status of the appointment.\nValid statuses include `scheduled`, `confirmed`, `checked-in`, `in-room`, `cancelled`.\nClinic custom statuses may also be used.\n", "type": "string" } } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"start_date_time\":\"2018-08-11 15:30\",\"end_date_time\":\"2018-08-11 16:00\",\"appointment_note\":\"Needs to move appointment back by a couple of hours\"}' -X PATCH https://subdomain.md-hq.com/api/v1/appointments/524563\n" } ] }, "delete": { "operationId": "deleteAppointment", "tags": [ "Appointments" ], "summary": "Destroy an appointment", "description": "Destroy an appointment.\nThis method should be used to completely remove an appointment.\nIf you are looking to cancel an appointment, instead use the update endpoint and set the status to `cancelled`.\n", "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "appointment_id", "in": "path", "description": "Appointment identifier.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Unauthorized" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X DELETE https://subdomain.md-hq.com/api/v1/appointments/542\n" } ] } }, "/appointments/{appointment_id}/reminders": { "get": { "operationId": "listAppointmentReminders", "parameters": [ { "name": "appointment_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the appointment" } ], "tags": [ "Appointment Reminders" ], "summary": "Get appointment reminders attached to an appointment", "description": "Get the appointment reminders attached to a specific appointment.\n", "security": [ { "basic_auth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/appointments/:appointment_id/reminders\n" } ] } }, "/appointments/{appointment_id}/reminders/email": { "post": { "operationId": "createEmailAppointmentReminder", "parameters": [ { "name": "appointment_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the appointment" } ], "tags": [ "Appointment Reminders" ], "summary": "Create an email reminder", "description": "Create an email reminder for an appointment", "security": [ { "basic_auth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_datetime": { "type": "string", "description": "Datetime for the reminder to be sent.\nThis field should be formatted as `YYYY-MM-DD HH:MM`.\n", "example": "2020-01-01 09:00" }, "subject": { "type": "string", "description": "Subject for the reminder email.", "example": "Reminder of your upcoming appointment" }, "text": { "type": "string", "description": "Body of the reminder email." } }, "required": [ "scheduled_datetime", "subject", "text" ] } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Unauthorized" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"scheduled_datetime\":\"2025-06-04 14:00:00\",\"subject\":\"You have an upcoming appointment\",\"text\":\"Hi {{pt_name}}, this is a reminder of your upcoming appointment.\"}' -X POST https://subdomain.md-hq.com/api/v1/appointments/748/reminders/email\n" } ] } }, "/appointments/{appointment_id}/reminders/sms": { "post": { "operationId": "createSmsAppointmentReminder", "parameters": [ { "name": "appointment_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the appointment" } ], "tags": [ "Appointment Reminders" ], "summary": "Create an SMS reminder", "description": "Create an SMS reminder for an appointment", "security": [ { "basic_auth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_datetime": { "type": "string", "description": "Datetime for the reminder to be sent.\nThis field should be formatted as `YYYY-MM-DD HH:MM`.\n", "example": "2020-01-02 08:00" }, "text": { "type": "string", "description": "Body of the reminder SMS." } }, "required": [ "scheduled_datetime", "text" ] } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Unauthorized" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"scheduled_datetime\":\"2025-06-04 16:30:00\",\"subject\": null,\"text\":\"Hi {pt_name}}, we will see you in an hour!\"}' -X POST https://subdomain.md-hq.com/api/v1/appointments/748/reminders/sms\n" } ] } }, "/appointment_types": { "get": { "operationId": "listAppointmentTypes", "tags": [ "Appointment Types" ], "summary": "Get all appointment types", "description": "Get all appointment types\nIf the `email_reminder_hrs_before` or `sms_reminder_hrs_before` values are less than\nzero, it means that they inherit the timing from the default practice settings.\n", "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "include_deleted", "in": "query", "description": "If specified and not empty, results will include deleted appointment types. Any non-empty value is treated as true.", "required": false, "example": "y", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Limit of how many records to return.\nOften used in conjunction with offset for pagination.\n", "required": false, "schema": { "type": "integer", "default": 1000, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Offset of where to start the returned records.\nOften used in conjunction with limit for pagination.\n", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "appointment_type" ] }, "id": { "type": "integer" }, "name": { "type": "string" }, "name_portal": { "type": "string" }, "color_hex": { "type": "string" }, "description": { "type": "string" }, "allow_on_portal": { "type": "boolean" }, "number_of_overlaps_to_allow": { "type": "integer" }, "portal_notice": { "type": "string" }, "which_providers": { "type": "array", "items": { "type": "integer" } }, "default_length": { "type": "integer" }, "default_status": { "type": "string" }, "sort_order": { "type": "integer" }, "telemedicine": { "type": "boolean" }, "email_notice_on": { "type": "boolean" }, "email_notice": { "type": "string" }, "email_notice_subject": { "type": "string" }, "email_reminder_on": { "type": "boolean" }, "email_reminder_hrs_before": { "type": "integer" }, "sms_reminder_on": { "type": "boolean" }, "sms_reminder": { "type": "string" }, "sms_reminder_hrs_before": { "type": "integer" }, "is_active": { "type": "boolean" }, "inactive_date": { "type": [ "string", "null" ], "format": "datetime" }, "created": { "type": "string", "format": "datetime" }, "created_by": { "type": "integer" } } } } } } } } }, "400": { "description": "Unauthorized" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/appointment_types\n" } ] }, "post": { "operationId": "createAppointmentType", "tags": [ "Appointment Types" ], "summary": "Create a new appointment type", "description": "Creates a new appointment type for the practice. Appointment types define the\ndefault duration, color, portal visibility, and automated reminder settings\nfor appointments of this type.\n\nNote: New appointment types are always created as active. To deactivate an\nappointment type, use the update endpoint after creation.\n", "security": [ { "basic_auth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "default_length" ], "properties": { "name": { "type": "string", "description": "The name of the appointment type. Must be unique and contain\nat least one letter or number.\n", "example": "New Patient Consultation" }, "default_length": { "type": "integer", "minimum": 5, "maximum": 720, "description": "Default duration in minutes. Must be between 5 minutes\nand 12 hours (720 minutes).\n", "example": 60 }, "name_portal": { "type": "string", "description": "Name displayed on the patient portal. Defaults to the\nsame value as name if not specified.\n", "example": "Initial Consultation" }, "color_hex": { "type": "string", "pattern": "^[0-9A-Fa-f]{6}$", "description": "Six-character hexadecimal color code (without #) for\ncalendar display. A random color is assigned if not specified.\n", "example": "3498DB" }, "description": { "type": "string", "description": "Internal description of the appointment type.", "example": "First visit for new patients" }, "allow_on_portal": { "type": "boolean", "default": false, "description": "Whether patients can book this type via the portal." }, "number_of_overlaps_to_allow": { "type": "integer", "minimum": 1, "maximum": 40, "default": 1, "description": "Maximum concurrent appointments of this type allowed\n(for group appointments).\n" }, "portal_notice": { "type": "string", "description": "Notice displayed to patients when booking via portal." }, "which_providers": { "type": "array", "items": { "type": "integer" }, "description": "Array of provider IDs who can have this appointment type.\nUse [0] for all providers.\n", "example": [ 1, 2, 5 ] }, "sort_order": { "type": "integer", "default": 0, "description": "Display order in appointment type lists." }, "telemedicine": { "type": "boolean", "default": false, "description": "Whether this is a telemedicine appointment type." }, "email_notice_on": { "type": "boolean", "default": false, "description": "Send email notification when appointment is created." }, "email_notice": { "type": "string", "description": "Email body for appointment creation notification." }, "email_notice_subject": { "type": "string", "default": "You have a new appointment", "description": "Subject line for appointment creation email." }, "email_reminder_on": { "type": "boolean", "default": false, "description": "Send automated email reminder before appointment." }, "email_reminder": { "type": "string", "description": "Email body for reminder." }, "email_reminder_subject": { "type": "string", "default": "Reminder about your upcoming appointment", "description": "Subject line for reminder email." }, "email_reminder_hrs_before": { "type": "integer", "minimum": 1, "maximum": 720, "default": 48, "description": "Hours before appointment to send email reminder\n(1 hour to 30 days).\n" }, "sms_reminder_on": { "type": "boolean", "default": false, "description": "Send automated SMS reminder before appointment." }, "sms_reminder": { "type": "string", "maxLength": 220, "description": "SMS message text for reminder (max 220 characters)." }, "sms_reminder_hrs_before": { "type": "integer", "minimum": 1, "maximum": 720, "default": 24, "description": "Hours before appointment to send SMS reminder\n(1 hour to 30 days).\n" } } } } } }, "responses": { "200": { "description": "Appointment type created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "appointment_type" ] }, "id": { "type": "integer" }, "name": { "type": "string" }, "name_portal": { "type": "string" }, "color_hex": { "type": "string" }, "description": { "type": "string" }, "allow_on_portal": { "type": "boolean" }, "number_of_overlaps_to_allow": { "type": "integer" }, "portal_notice": { "type": "string" }, "which_providers": { "type": "array", "items": { "type": "integer" } }, "default_length": { "type": "integer" }, "sort_order": { "type": "integer" }, "telemedicine": { "type": "boolean" }, "email_notice_on": { "type": "boolean" }, "email_notice": { "type": "string" }, "email_notice_subject": { "type": "string" }, "email_reminder_on": { "type": "boolean" }, "email_reminder": { "type": "string" }, "email_reminder_subject": { "type": "string" }, "email_reminder_hrs_before": { "type": "integer" }, "sms_reminder_on": { "type": "boolean" }, "sms_reminder": { "type": "string" }, "sms_reminder_hrs_before": { "type": "integer" }, "is_active": { "type": "boolean" }, "inactive_date": { "type": [ "string", "null" ] }, "created": { "type": "string", "format": "datetime" }, "created_by": { "type": "integer" } } } } } }, "400": { "description": "Bad Request - Validation error" }, "500": { "description": "Server Error - Unable to create appointment type" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" \\\n --data '{\"name\":\"New Patient Consultation\",\"default_length\":60,\"color_hex\":\"3498DB\",\"allow_on_portal\":true}' \\\n -X POST https://subdomain.md-hq.com/api/v1/appointment_types\n" } ] } }, "/charges": { "get": { "operationId": "listAllCharges", "tags": [ "Charges" ], "summary": "Get All Charges (System-wide)", "description": "Get all patient charges across all patients. This endpoint returns transactional\ncharges (not charge definitions from the master ledger - use `/charge_master` for that).\n\nResults can be filtered by date range using either the creation date or transaction date.\n", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 100 }, "description": "The maximum number of charges to return (default is 100)." }, { "in": "query", "name": "offset", "schema": { "type": "integer", "default": 0 }, "description": "Offset the list to allow cycling through charges." }, { "in": "query", "name": "date_method", "schema": { "type": "string", "enum": [ "created", "transaction" ], "default": "created" }, "description": "If filtering by date range, should the range be calculated by date\nthe charge was created, or the recorded transaction date?\nValid arguments are 'created' and 'transaction' (created is the default).\n" }, { "in": "query", "name": "start_date", "schema": { "type": "string", "format": "date" }, "description": "Show charges from after this date (calculated by date_method)." }, { "in": "query", "name": "end_date", "schema": { "type": "string", "format": "date" }, "description": "Show charges from before this date (calculated by date_method)." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "patient_charge" ] }, "id": { "type": "integer" }, "name": { "type": "string" }, "patient_id": { "type": "integer" }, "encounter_id": { "type": "integer" }, "amount": { "type": "string" }, "quantity": { "type": "integer" }, "discount_multiplier": { "type": "number", "description": "Discount level applied to the charge (1.0 = no discount)" }, "charge_master_details": { "type": "object", "description": "Details from the charge master definition" }, "billing_rules": { "type": "object", "description": "Insurance billing configuration" }, "location_identifier": { "type": [ "string", "null" ] }, "additional_details": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "is_voided": { "type": "boolean" }, "owner_id": { "type": "integer" }, "addedby": { "type": "integer" }, "created": { "type": "string", "format": "datetime" }, "transaction_date": { "type": "string", "format": "date" }, "payment_details": { "type": [ "object", "null" ], "description": "Payment allocation details (null if no payments applied)", "properties": { "total_payment": { "type": "string", "description": "Total payment amount applied to this charge" }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "allocation_id": { "type": "integer" }, "allocation_amount": { "type": "string" }, "allocation_date": { "type": "string", "format": "date-time" }, "allocation_addedby": { "type": "integer" }, "payment_id": { "type": "integer" }, "payment_src_patient": { "type": "integer" }, "payment_total_value": { "type": "string" }, "payment_method": { "type": "string" }, "payment_note": { "type": [ "string", "null" ] }, "payment_addedby": { "type": "integer" }, "payment_date": { "type": "string", "format": "date" }, "payment_created_date": { "type": "string", "format": "date-time" } } } } } }, "is_deleted": { "type": "boolean" } } } } } } } } }, "400": { "description": "Bad Request - Invalid date parameters" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET \"https://subdomain.md-hq.com/api/v1/charges?limit=100&offset=0&start_date=2024-01-01&end_date=2024-01-31\"\n" } ] } }, "/charges/{charge_id}": { "get": { "operationId": "showChargeById", "tags": [ "Charges" ], "summary": "Get a Single Charge by ID", "description": "Retrieve a single patient charge by its ID. This returns the transactional charge\ndetails regardless of which patient it belongs to.\n", "parameters": [ { "in": "path", "name": "charge_id", "required": true, "schema": { "type": "integer" }, "description": "The ID of the charge to retrieve." }, { "in": "query", "name": "include_deleted", "schema": { "type": "boolean", "default": false }, "description": "If true, will return the charge even if it has been deleted.\nUseful for retrieving historical records.\n" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "patient_charge" ] }, "id": { "type": "integer" }, "name": { "type": "string" }, "patient_id": { "type": "integer" }, "encounter_id": { "type": "integer" }, "amount": { "type": "string" }, "quantity": { "type": "integer" }, "discount_multiplier": { "type": "number", "description": "Discount level applied to the charge (1.0 = no discount)" }, "charge_master_details": { "type": "object", "description": "Details from the charge master definition", "properties": { "object": { "type": "string", "enum": [ "charge_definition" ] }, "id": { "type": "integer" }, "name": { "type": "string" }, "name_for_pt_portal": { "type": "string" }, "category": { "type": "string" }, "cpt_code": { "type": "string" }, "retail": { "type": "string" }, "wholesale": { "type": "string" } } }, "billing_rules": { "type": "object", "description": "Insurance billing configuration", "properties": { "add_to_insurance_claim": { "type": "boolean" }, "cpt_code": { "type": "string" }, "cpt_modifiers": { "type": "string" }, "amt_billed_to_insurance": { "type": "string" }, "amt_paid_by_insurance": { "type": "string" }, "amt_written_off": { "type": "string" } } }, "location_identifier": { "type": [ "string", "null" ] }, "additional_details": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "is_voided": { "type": "boolean" }, "date_voided": { "type": [ "string", "null" ] }, "owner_id": { "type": "integer" }, "addedby": { "type": "integer" }, "created": { "type": "string", "format": "datetime" }, "transaction_date": { "type": "string", "format": "date" }, "payment_details": { "type": [ "object", "null" ], "description": "Payment allocation details (null if no payments applied)", "properties": { "total_payment": { "type": "string", "description": "Total payment amount applied to this charge" }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "allocation_id": { "type": "integer" }, "allocation_amount": { "type": "string" }, "allocation_date": { "type": "string", "format": "date-time" }, "allocation_addedby": { "type": "integer" }, "payment_id": { "type": "integer" }, "payment_src_patient": { "type": "integer" }, "payment_total_value": { "type": "string" }, "payment_method": { "type": "string" }, "payment_note": { "type": [ "string", "null" ] }, "payment_addedby": { "type": "integer" }, "payment_date": { "type": "string", "format": "date" }, "payment_created_date": { "type": "string", "format": "date-time" } } } } } }, "is_deleted": { "type": "boolean" }, "date_deleted": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Bad Request - Charge not found or invalid ID" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET \"https://subdomain.md-hq.com/api/v1/charges/12345\"\n" }, { "lang": "cURL", "label": "CLI (include deleted)", "source": "curl -H \"Authorization: Basic CREDS\" -X GET \"https://subdomain.md-hq.com/api/v1/charges/12345?include_deleted=true\"\n" } ] } }, "/charge_master": { "get": { "operationId": "listCharges", "tags": [ "Charges" ], "summary": "Get Charge Definitions", "description": "Get All Charge Definitions from the Master Ledger", "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 100 } }, { "name": "offset", "description": "If the returned data indicates that there is more than the limit\nresponses (has_more: true), then it will offset the list to allow \nyou to cycle through charge definitions.\n", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Rate-Limit": { "description": "calls per hour allowed by the user", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "charge_definition" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "name_for_pt_portal": { "type": "string" }, "category": { "type": "string" }, "cpt_code": { "type": "string" }, "nicknames": { "type": "array", "items": { "type": "string" } }, "barcode_upc": { "type": "string" }, "description": { "type": "string" }, "retail": { "type": "string" }, "wholesale": { "type": "string" }, "is_supply": { "type": "boolean" }, "time_required": { "type": [ "string", "null" ] }, "is_taxable": { "type": "boolean" }, "tax_rate": { "type": [ "string", "null" ] }, "is_special": { "type": "boolean" }, "add_to_insurance_claims": { "type": "boolean" }, "inactive": { "type": "boolean" }, "addedby": { "type": "string" }, "created": { "type": "string", "format": "datetime" } } } } } } } } }, "400": { "description": "Unauthorized" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/charge_master?limit=10&offset=0\n" } ] } }, "/charge_master/{charge_id}": { "get": { "operationId": "showCharge", "tags": [ "Charges" ], "summary": "Get Single Charge Definition", "description": "Get Single Charge Definition from the Master Ledger", "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "charge_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Rate-Limit": { "description": "calls per hour allowed by the user", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "charge_definition" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "name_for_pt_portal": { "type": "string" }, "category": { "type": "string" }, "cpt_code": { "type": "string" }, "nicknames": { "type": "array", "items": { "type": "string" } }, "barcode_upc": { "type": "string" }, "description": { "type": "string" }, "retail": { "type": "string" }, "wholesale": { "type": "string" }, "is_supply": { "type": "boolean" }, "time_required": { "type": [ "string", "null" ] }, "is_taxable": { "type": "boolean" }, "tax_rate": { "type": [ "string", "null" ] }, "is_special": { "type": "boolean" }, "add_to_insurance_claims": { "type": "boolean" }, "inactive": { "type": "boolean" }, "addedby": { "type": "string" }, "created": { "type": "string", "format": "datetime" } } } } } }, "400": { "description": "Unauthorized" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/charge_master/2\n" } ] } }, "/patients/{pt_id}/charges": { "get": { "operationId": "listPatientCharges", "tags": [ "Charges" ], "summary": "Get Patient Charges", "description": "Get All Patient Charges", "parameters": [ { "in": "path", "name": "pt_id", "required": true, "schema": { "type": "integer" }, "description": "The ID of the patient." }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "The maximum number of charges to return (default is 100)." }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "Offset the list to allow cycling through patient charges." }, { "in": "query", "name": "date_method", "schema": { "type": "string" }, "description": "If you're filtering by date range, should the range be calculated by date\nthe charge was created, or the recorded transaction date? Valid arguments are\n'created' and 'transaction' (created is the default).\n" }, { "in": "query", "name": "start_date", "schema": { "type": "string" }, "description": "Show charges from after this date (calculated by date_method).\n" }, { "in": "query", "name": "end_date", "schema": { "type": "string" }, "description": "Show charges from before this date (calculated by date_method).\n" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "patient_charge" ] }, "id": { "type": "integer" }, "name": { "type": "string" }, "patient_id": { "type": "integer" }, "encounter_id": { "type": "integer" }, "amount": { "type": "string" }, "quantity": { "type": "integer" }, "discount_multiplier": { "type": "integer" }, "charge_master_details": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "charge_definition" ] }, "id": { "type": "integer" }, "name": { "type": "string" }, "name_for_pt_portal": { "type": "string" }, "category": { "type": "string" }, "cpt_code": { "type": "string" }, "nicknames": { "type": "array", "items": { "type": "string" } }, "barcode_upc": { "type": "string" }, "description": { "type": "string" }, "retail": { "type": "string" }, "wholesale": { "type": "string" }, "is_supply": { "type": "boolean" }, "time_required": { "type": [ "integer", "null" ] }, "is_taxable": { "type": "boolean" }, "add_to_insurance_claim": { "type": "boolean" }, "inactive": { "type": "boolean" }, "addedby": { "type": "string" }, "created": { "type": "string", "format": "datetime" } } }, "billing_rules": { "type": "object", "properties": { "add_to_insurance_claim": { "type": "boolean" }, "cpt_code": { "type": "string" }, "cpt_modifiers": { "type": "string" }, "amt_billed_to_insurance": { "type": "string" }, "amt_paid_by_insurance": { "type": "string" }, "amt_written_off": { "type": "string" }, "date_paid_by_insurance": { "type": [ "string", "null" ] }, "which_insurance_to_bill": { "type": [ "string", "null" ] }, "justifying_diagnoses": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "assessment" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "icd_version": { "type": "string" }, "code": { "type": "string" }, "addedby": { "type": "string" }, "created": { "type": "string", "format": "datetime" }, "diagnosis_history": { "type": "object", "properties": { "onset_date": { "type": [ "string", "null" ] }, "is_primary": { "type": "boolean" }, "initial_treatment_date": { "type": [ "string", "null" ] } } } } } } } }, "location_identifier": { "type": [ "string", "null" ] }, "additional_details": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "is_voided": { "type": "boolean" }, "date_voided": { "type": [ "string", "null" ] }, "owner_id": { "type": "integer" }, "addedby": { "type": "integer" }, "created": { "type": "string", "format": "datetime" }, "transaction_date": { "type": "string", "format": "date" }, "payment_details": { "type": [ "string", "null" ] }, "is_deleted": { "type": "boolean" }, "date_deleted": { "type": [ "string", "null" ] } } } } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET \"https://subdomain.md-hq.com/api/v1/patients/2/charges?limit=100&offset=0&start_date=2018-10-01&end_date=2018-10-31\"\n" } ] } }, "/patients/{pt_id}/encounters/{encounter_id}/charges": { "get": { "operationId": "listEncounterCharges", "tags": [ "Charges" ], "summary": "Get Charges from Encounter", "description": "Get All Charges from a Single Encounter", "parameters": [ { "in": "path", "name": "pt_id", "required": true, "schema": { "type": "integer" }, "description": "The ID of the patient." }, { "in": "path", "name": "encounter_id", "required": true, "schema": { "type": "integer" }, "description": "The ID of the encounter." }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "The maximum number of charge definitions to return (default is 100)." }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "Offset the list to allow cycling through charge definitions." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "description": { "type": "string", "enum": [ "encounter_charges" ] }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "patient_charge" ] }, "id": { "type": "integer" }, "name": { "type": "string" }, "patient_id": { "type": "integer" }, "encounter_id": { "type": "integer" }, "amount": { "type": "string" }, "quantity": { "type": "integer" }, "discount_multiplier": { "type": "integer" }, "charge_master_details": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "charge_definition" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "name_for_pt_portal": { "type": "string" }, "category": { "type": "string" }, "cpt_code": { "type": "string" }, "nicknames": { "type": "array", "items": { "type": "string" } }, "barcode_upc": { "type": "string" }, "description": { "type": "string" }, "retail": { "type": "string" }, "wholesale": { "type": "string" }, "is_supply": { "type": "boolean" }, "time_required": { "type": "string" }, "is_taxable": { "type": "boolean" }, "tax_rate": { "type": "integer" }, "is_special": { "type": "boolean" }, "add_to_insurance_claims": { "type": "boolean" }, "inactive": { "type": "boolean" }, "addedby": { "type": "string" }, "created": { "type": "string", "format": "datetime" } } }, "billing_rules": { "type": "object", "properties": { "add_to_insurance_claim": { "type": "boolean" }, "cpt_code": { "type": "string" }, "cpt_modifiers": { "type": "string" }, "amt_billed_to_insurance": { "type": "string" }, "amt_paid_by_insurance": { "type": "string" }, "amt_written_off": { "type": "string" }, "date_paid_by_insurance": { "type": [ "string", "null" ], "format": "datetime" }, "which_insurance_to_bill": { "type": [ "string", "null" ] }, "justifying_diagnoses": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "assessment" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "icd_version": { "type": "string" }, "code": { "type": "string" }, "addedby": { "type": "string" }, "created": { "type": "string", "format": "datetime" }, "diagnosis_history": { "type": "object", "properties": { "onset_date": { "type": [ "string", "null" ] }, "is_primary": { "type": "boolean" }, "initial_treatment_date": { "type": [ "string", "null" ] } } } } } } } }, "location_identifier": { "type": [ "string", "null" ] }, "additional_details": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "is_voided": { "type": "boolean" }, "date_voided": { "type": [ "string", "null" ], "format": "datetime" }, "owner_id": { "type": "integer" }, "addedby": { "type": "integer" }, "created": { "type": "string", "format": "datetime" }, "transaction_date": { "type": "string", "format": "date" }, "payment_details": { "type": [ "string", "null" ] }, "is_deleted": { "type": "boolean" }, "date_deleted": { "type": [ "string", "null" ], "format": "datetime" } } } } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET \"https://subdomain.md-hq.com/api/v1/patients/2/encounters/423/charges\"\n" } ] } }, "/delta/{resource_type}": { "get": { "operationId": "listDeltas", "tags": [ "Deltas" ], "summary": "Get all differences", "description": "Get all differences of resources in a specified date time range", "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "resource_type", "in": "path", "description": "Resource type. Valid resources include `appointments`, `rxs`, `pt_rx`, `drugs`,\n`supplements`, `orders`, `pt_orders`, `documents`, `patients`, `users`, `tags`,\n`pt_tags`, `tasks`.\n", "required": true, "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Starting date of the date range. The start date should be formatted as `YYYY-MM-DD`.\nThe start date can also include time, and should be formatted as `YYYY-MM-DD HH:MM:SS`.\n", "required": true, "example": "2020-01-01", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "description": "Ending date of the date range. The end date should be formatted as `YYYY-MM-DD`.\nThe end date can also include time, and should be formatted as `YYYY-MM-DD HH:MM:SS`.\nThe end date must be later than the start date, but can **NOT** be longer than a week in length.\n", "required": true, "example": "2020-02-01", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Rate-Limit": { "description": "calls per hour allowed by the user", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "delta" ] }, "resource_type": { "type": "string", "enum": [ "documents" ] }, "from_date": { "type": "string", "format": "datetime" }, "until_date": { "type": "string", "format": "datetime" }, "delta_data": { "type": "object", "properties": { "created": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "dateadded": { "type": "string", "format": "datetime" }, "addedby": { "type": "integer" }, "patient_id": { "type": "integer" }, "system_type": { "type": "string" }, "details_api_url": { "type": "string" } } } }, "modified": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "dateadded": { "type": "string", "format": "datetime" }, "addedby": { "type": "integer" }, "patient_id": { "type": "integer" }, "system_type": { "type": "string" }, "details_api_url": { "type": "string" } } } }, "removed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "dateadded": { "type": "string", "format": "datetime" }, "addedby": { "type": "integer" }, "patient_id": { "type": "integer" }, "system_type": { "type": "string" }, "details_api_url": { "type": "string" } } } } } } } } } } }, "400": { "description": "Unauthorized" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET \"https://subdomain.md-hq/api/v1/delta/documents?start_date=2020-01-20&end_date=2020-01-22\"\n" } ] } }, "/inventory": { "get": { "operationId": "listInventory", "tags": [ "Inventory" ], "summary": "Get all inventory items", "description": "Returns a paginated list of inventory items. Inventory items can be linked to medications (rxs),\nsupplements (plan_other), or general products. Each item tracks stock levels, expiration dates,\nand is associated with a charge master entry.\n\nAll dates are returned in UTC format.\n", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return. Defaults to 100, max is 100.", "schema": { "type": "integer", "default": 100, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of items to skip for pagination. Use when `has_more` is true.", "schema": { "type": "integer", "default": 0 } }, { "name": "type", "in": "query", "description": "Filter by inventory type (e.g., \"Drug (RX)\", \"General\"). Uses partial matching.", "schema": { "type": "string" } }, { "name": "manufacturer", "in": "query", "description": "Filter by manufacturer name. Uses partial matching.", "schema": { "type": "string" } }, { "name": "include_deleted", "in": "query", "description": "Set to the string 'true' to include soft-deleted items. Other values are ignored.", "schema": { "type": "string" }, "example": "true" }, { "name": "include_discontinued", "in": "query", "description": "Set to the string 'true' to include discontinued items. Other values are ignored.", "schema": { "type": "string" }, "example": "true" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "total_count": { "type": "integer", "description": "Number of items returned in this response" }, "has_more": { "type": "boolean", "description": "Whether more items exist beyond the current page" }, "data": { "type": "array", "description": "Array of inventory item objects", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique inventory item ID" }, "name": { "type": "string", "description": "Name of the inventory item" }, "nickname": { "type": [ "string", "null" ], "description": "Short nickname for the item" }, "linked_product_type": { "type": "string", "enum": [ "rxs", "plan_other", "general" ], "description": "Type of linked product" }, "linked_product_id": { "type": [ "integer", "null" ], "description": "ID of the linked product" }, "charge_id": { "type": "integer", "description": "Associated charge master ID" }, "preferred_stock_level": { "type": "integer", "description": "Target stock level" }, "current_quantity": { "type": "integer", "description": "Current quantity in stock" }, "manufacturer": { "type": [ "string", "null" ], "description": "Manufacturer name" }, "expiration_date": { "type": [ "string", "null" ], "format": "date", "description": "Expiration date" }, "lot_number": { "type": [ "string", "null" ], "description": "Lot number" }, "discontinued": { "type": "boolean", "description": "Whether item is discontinued" }, "created": { "type": "string", "format": "date-time", "description": "When the item was created (UTC)" } } } } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET \"https://subdomain.md-hq.com/api/v1/inventory?limit=10&type=Drug\"\n" } ] }, "post": { "operationId": "createInventory", "tags": [ "Inventory" ], "summary": "Create a new inventory item", "description": "Creates a new inventory item. The item must be linked to either a medication (rxs),\nsupplement (plan_other), or can be a general product.\n", "requestBody": { "required": true, "description": "Inventory item data", "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "linked_product_type", "charge_id", "preferred_stock_level", "current_quantity" ], "properties": { "name": { "type": "string", "description": "Name of the inventory item" }, "nickname": { "type": "string", "description": "Short nickname for the item" }, "linked_product_type": { "type": "string", "enum": [ "rxs", "plan_other", "general" ], "description": "Type of linked product:\n- `rxs`: Links to a medication in the drugs database\n- `plan_other`: Links to a supplement\n- `general`: General inventory item (no linked product)\n" }, "linked_product_id": { "type": "integer", "description": "ID of the linked product. Required for \"rxs\" and \"plan_other\" types." }, "charge_id": { "type": "integer", "description": "ID of the associated charge in the charge master" }, "preferred_stock_level": { "type": "integer", "minimum": 0, "description": "Target stock level to maintain" }, "current_quantity": { "type": "integer", "minimum": 0, "description": "Current quantity in stock" }, "preferred_restock_level": { "type": "integer", "minimum": 0, "description": "Level at which to trigger restocking" }, "manufacturer": { "type": "string", "description": "Manufacturer name" }, "expiration_date": { "type": "string", "format": "date", "description": "Expiration date (must be in the future)" }, "lot_number": { "type": "string", "description": "Lot number for tracking" }, "discontinued": { "type": "boolean", "description": "Whether the item is discontinued" }, "date_discontinued": { "type": "string", "format": "date", "description": "Date the item was discontinued" }, "external_identifier": { "type": "string", "description": "External system identifier for integration" }, "location": { "type": "string", "description": "Location name (for multi-location practices)" }, "package_properties": { "type": "object", "description": "Package-specific properties", "properties": { "ndc_code": { "type": "string", "description": "National Drug Code (for medications)" }, "generic_for": { "type": "string", "description": "Brand name this is generic for" }, "charge_per_dose": { "type": "string", "description": "Charge amount per dose" }, "charge_per_dispense": { "type": "string", "description": "Charge amount per dispense" }, "cost_per_dose": { "type": "string", "description": "Cost per dose" }, "patient_information_url": { "type": "string", "description": "URL to patient information sheet" }, "package_form": { "type": "string", "description": "Form of packaging" }, "product_code": { "type": "string", "description": "Product code" }, "description": { "type": "string", "description": "Product description/notes" } } } } } } } }, "responses": { "200": { "description": "OK - Returns the created inventory item", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique inventory item ID" }, "name": { "type": "string" }, "linked_product_type": { "type": "string", "enum": [ "rxs", "plan_other", "general" ] }, "linked_product_id": { "type": [ "integer", "null" ] }, "charge_id": { "type": "integer" }, "preferred_stock_level": { "type": "integer" }, "current_quantity": { "type": "integer" }, "created": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Bad Request" }, "500": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "example": "validation_error" } } } } } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" \\\n -H \"Content-Type: application/json\" \\\n -X POST https://subdomain.md-hq.com/api/v1/inventory \\\n -d '{\"name\":\"Aspirin 325mg\",\"linked_product_type\":\"rxs\",\"linked_product_id\":1234,\"charge_id\":456,\"preferred_stock_level\":100,\"current_quantity\":50}'\n" } ] } }, "/inventory/{id}": { "get": { "operationId": "showInventory", "tags": [ "Inventory" ], "summary": "Get a single inventory item", "description": "Retrieves detailed information about a single inventory item by its ID.\nIncludes linked product details (drug or supplement) and charge information.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The inventory item ID", "schema": { "type": "integer" } }, { "name": "include_deleted", "in": "query", "description": "Set to true to retrieve soft-deleted items.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK - Returns the inventory item object", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique inventory item ID" }, "name": { "type": "string", "description": "Name of the inventory item" }, "nickname": { "type": [ "string", "null" ], "description": "Short nickname for the item" }, "linked_product_type": { "type": "string", "enum": [ "rxs", "plan_other", "general" ], "description": "Type of linked product" }, "linked_product_id": { "type": [ "integer", "null" ], "description": "ID of the linked product" }, "charge_id": { "type": "integer", "description": "Associated charge master ID" }, "preferred_stock_level": { "type": "integer", "description": "Target stock level" }, "current_quantity": { "type": "integer", "description": "Current quantity in stock" }, "manufacturer": { "type": [ "string", "null" ], "description": "Manufacturer name" }, "expiration_date": { "type": [ "string", "null" ], "format": "date", "description": "Expiration date" }, "lot_number": { "type": [ "string", "null" ], "description": "Lot number" }, "discontinued": { "type": "boolean", "description": "Whether item is discontinued" }, "package_properties": { "type": "object", "description": "Package-specific properties" }, "created": { "type": "string", "format": "date-time", "description": "When the item was created (UTC)" } } } } } }, "400": { "description": "Bad Request - Invalid Inventory ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid Inventory ID" } } } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/inventory/231\n" } ] }, "patch": { "operationId": "updateInventory", "tags": [ "Inventory" ], "summary": "Update an inventory item", "description": "Updates an existing inventory item. Only the fields provided will be updated.\nNote: `linked_product_type` and `linked_product_id` cannot be changed after creation.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The inventory item ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "description": "Fields to update", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the inventory item" }, "nickname": { "type": "string", "description": "Short nickname" }, "charge_id": { "type": "integer", "description": "ID of the associated charge" }, "preferred_stock_level": { "type": "integer", "minimum": 0, "description": "Target stock level" }, "current_quantity": { "type": "integer", "minimum": 0, "description": "Current quantity in stock" }, "preferred_restock_level": { "type": "integer", "minimum": 0, "description": "Restock trigger level" }, "manufacturer": { "type": "string", "description": "Manufacturer name" }, "expiration_date": { "type": "string", "format": "date", "description": "Expiration date (must be in the future)" }, "lot_number": { "type": "string", "description": "Lot number" }, "discontinued": { "type": "boolean", "description": "Whether item is discontinued" }, "date_discontinued": { "type": "string", "format": "date", "description": "Discontinuation date" }, "external_identifier": { "type": "string", "description": "External system identifier" }, "location": { "type": "string", "description": "Location name" }, "package_properties": { "type": "object", "description": "Package-specific properties (only provided fields are updated)" } } } } } }, "responses": { "200": { "description": "OK - Returns the updated inventory item", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique inventory item ID" }, "name": { "type": "string" }, "linked_product_type": { "type": "string", "enum": [ "rxs", "plan_other", "general" ] }, "linked_product_id": { "type": [ "integer", "null" ] }, "charge_id": { "type": "integer" }, "preferred_stock_level": { "type": "integer" }, "current_quantity": { "type": "integer" }, "created": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Bad Request - Invalid Inventory ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid Inventory ID" } } } } } }, "500": { "description": "Validation Error" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" \\\n -H \"Content-Type: application/json\" \\\n -X PATCH https://subdomain.md-hq.com/api/v1/inventory/231 \\\n -d '{\"current_quantity\":75,\"preferred_stock_level\":150}'\n" } ] } }, "/drugs/frequencies": { "get": { "operationId": "listDrugFrequencies", "tags": [ "Drugs" ], "summary": "Get medication frequency options", "description": "Returns a list of available medication frequencies (dosing intervals). Use these values\nwhen creating or displaying prescription information.\n\nThe `times_per_day` value is a numeric representation that can be used for calculations:\n- Values >= 1 represent doses per day (e.g., 2 = twice daily)\n- Values < 1 represent intervals longer than daily (e.g., 0.5 = every other day, 0.142857 = once weekly)\n", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable frequency name with abbreviation", "example": "QD (once a day)" }, "times_per_day": { "type": "string", "description": "Numeric value representing doses per day (as string, supports decimals)", "example": "1" } } } } } }, "example": { "object": "list", "data": [ { "name": "QD (once a day)", "times_per_day": "1" }, { "name": "BID (twice a day)", "times_per_day": "2" }, { "name": "TID (Three times a day)", "times_per_day": "3" }, { "name": "QID (4 times a day)", "times_per_day": "4" }, { "name": "PRN (as needed)", "times_per_day": "1" }, { "name": "QHS (before bed)", "times_per_day": "1" }, { "name": "QOD (every other day)", "times_per_day": ".5" }, { "name": "Qweek (once a week)", "times_per_day": ".142857" }, { "name": "Q4h (Every 4 hours)", "times_per_day": "6" }, { "name": "Q6h (Every 6 Hours)", "times_per_day": "4" } ] } } } }, "400": { "description": "Bad Request" }, "500": { "description": "Internal Server Error" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/drugs/frequencies\n" } ] } }, "/drugs/search/{term}": { "get": { "operationId": "searchDrugs", "tags": [ "Drugs" ], "summary": "Search for drugs by term", "description": "Please note: All dates listed are listed in UTC, so you’ll want to adjust for your local timezone. These\nendpoints allow to you search/get details about specific medications. If you are looking for API calls on\npatient-specific prescriptions as opposed to drug definitions, please use the\nPatient Prescriptions endpoint.\nAlso, these drug definitions are licensed data from Wolters Kluwer and your usage of these endpoints\nare limited to functions that you can perform in the EMR or patient portal. You may not use this drug data for\npurposes other than management of medications for your Cerbo patient population.\nYou can enter several terms with spaces between each (make sure to url-encode the\nsearch string, so spaces would be %20). Each term is treated as potentially a wildcard search so\n_tylen%203_ (_tylen 3_) would return _Tylenol 325mg_, _Tylenol Syrup 30mg_, etc.\n", "parameters": [ { "in": "path", "name": "term", "required": true, "schema": { "type": "string" }, "description": "Search term for drug name" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "Limit number of results" }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "Offset the results" }, { "in": "query", "name": "favorites-only", "schema": { "type": "boolean", "default": true }, "description": "Return only drugs from provider's favorites list" } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/drugs/search/tylenol\n" } ] } }, "/drugs/{drug_id}": { "get": { "operationId": "showDrug", "tags": [ "Drugs" ], "summary": "Get a single drug", "parameters": [ { "in": "path", "name": "drug_id", "schema": { "type": "integer" }, "description": "ID of drug" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/drugs/2\n" } ] } }, "/patients/{patient_id}/encounters": { "get": { "operationId": "listEncounters", "tags": [ "Encounters" ], "description": "Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC,\nso you'll want to adjust for your local timezone. The returned JSON will include prescribed medications,\nsupplements, recommendations (and other alternate plan items), diagnoses. One thing to note: the API\nis designed to return attachments (documents and images that are included in the encounter) with the\nresponse, but currently this functionality is disabled and an empty array will always be returned. \n", "summary": "Get All Encounters for a Patient", "parameters": [ { "in": "path", "name": "patient_id", "required": true, "schema": { "type": "integer" }, "description": "The ID of the patient." }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "The maximum number of encounters to return (default is 100)." }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "Offset the list to allow cycling through encounter notes." }, { "in": "query", "name": "type", "schema": { "type": "string" }, "description": "Limit results to a specific encounter note type (e.g., \"ov\" for office visit).\n" }, { "in": "query", "name": "signed_only", "schema": { "type": "boolean" }, "description": "If included and set to \"false,\" return all encounter notes, including those\nnot marked as signed.\n" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET \"https://subdomain.md-hq.com/api/v1/patients/2/encounters?limit=10&signed_only=false&type=ov\"\n" } ] } }, "/encounters/{encounter_id}": { "get": { "operationId": "showEncounter", "tags": [ "Encounters" ], "description": "Get a single encounter's details", "summary": "Get a single encounter's details", "parameters": [ { "in": "path", "name": "encounter_id", "required": true, "schema": { "type": "integer" }, "description": "The ID of the encounter note." } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/encounters/231\n" } ] }, "delete": { "operationId": "deleteEncounter", "tags": [ "Encounters" ], "summary": "Delete an Encounter", "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "encounter_id", "in": "path", "description": "Encounter identifier.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Encounter successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean", "enum": [ true ] }, "object": { "type": "string", "enum": [ "encounter" ] }, "id": { "type": "integer" }, "data": { "type": "null" }, "action": { "type": "string", "enum": [ "removed" ] }, "message": { "type": "string", "enum": [ "Encounter successfully deleted" ] } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X DELETE https://subdomain.md-hq.com/api/v1/encounters/1\n" } ] } }, "/encounters": { "post": { "operationId": "createEncounter", "tags": [ "Encounters" ], "summary": "Create a New Encounter on a Patient Chart", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pt_id": { "type": "integer", "description": "A valid ID of a non-archived patient." }, "date_of_service": { "type": "string", "format": "date", "description": "A time stamp (YYYY-MM-DD format preferred) representing the date the encounter took or will take place. Can be future or past." }, "title": { "type": "string", "description": "The title of the encounter note." }, "content": { "type": "string", "description": "The plaintext-formatted text of the encounter note." }, "encounter_type": { "type": "string", "description": "The two-letter abbreviation of the type of encounter note you are creating." }, "owner": { "type": "integer", "description": "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": { "type": "integer", "description": "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": { "201": { "description": "Encounter created successfully" }, "400": { "description": "Bad request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X POST \"https://subdomain.md-hq.com/api/v1/encounters\" -H \"Content-Type: application/json\" -d '{\n \"pt_id\": 123,\n \"date_of_service\": \"2023-10-03\",\n \"title\": \"Sample Encounter\",\n \"content\": \"This is a sample encounter note.\",\n \"encounter_type\": \"ET\",\n \"owner\": 456,\n \"parent_encounter\": 789\n}'\n" } ] } }, "/encounter_types": { "get": { "operationId": "listEncounterTypes", "tags": [ "Encounter Types" ], "summary": "Get all encounter types", "description": "Returns a list of all encounter types configured in the system. Encounter types define\nthe categories of clinical encounters (e.g., Office Visit, Phone Call, Email Consult).\n\nUse this endpoint to retrieve valid `encounter_type` values when creating encounters\nvia the `POST /encounters` endpoint.\n", "parameters": [ { "name": "include_deleted", "in": "query", "description": "When set to any truthy value, includes soft-deleted encounter types in the response.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "total_count": { "type": "integer", "description": "Number of encounter types returned" }, "has_more": { "type": "boolean", "example": false, "description": "Always false (no pagination)" }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the encounter type", "example": "Office Visit" }, "encounter_type": { "type": "string", "description": "Abbreviation/code used when creating encounters", "example": "ov" }, "is_face_to_face": { "type": "boolean", "description": "Whether this is an in-person encounter type", "example": true }, "description": { "type": "string", "description": "Description of the encounter type" }, "sort_priority": { "type": "integer", "description": "Sort order (lower numbers appear first)", "example": 1 }, "place_of_service_code": { "type": "string", "description": "Healthcare place of service code for billing. Defaults to 11 (Office).", "example": "11" }, "provider_taxonomy": { "type": [ "string", "null" ], "description": "Provider taxonomy code for EDI/HFCFA billing" }, "deletedby": { "type": [ "integer", "null" ], "description": "User ID who deleted this type (null if not deleted)" } } } } } }, "example": { "object": "list", "total_count": 8, "has_more": false, "data": [ { "name": "Office Visit", "encounter_type": "ov", "is_face_to_face": true, "description": "", "sort_priority": 1, "place_of_service_code": "11", "provider_taxonomy": null, "deletedby": null }, { "name": "Phone Call", "encounter_type": "pm", "is_face_to_face": false, "description": "", "sort_priority": 2, "place_of_service_code": "99", "provider_taxonomy": null, "deletedby": null } ] } } } }, "400": { "description": "Bad Request" }, "500": { "description": "Internal Server Error" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/encounter_types\n" } ] } }, "/patients/{id}/extended_details": { "get": { "operationId": "getExtendedPatientDetails", "tags": [ "Extended Patient Details" ], "summary": "Get all patients with extended (research) details", "description": "Most data about an individual patient is available through specific calls for patient documents,\ndemographics, vitals, etc. However, for research purposes you often want to pull a large amount of\ndiscrete data about patients, so Cerbo provides a specific endpoint that aggregates most relevant data\ninto a single call.\n\nTo access your patient's extended data, first run an API call to return all patients, then loop through the\npatient ids returned in that response and fetch each patient's extended details.\n\nPlease note: All dates listed are listed in UTC, so you'll want to adjust for your local timezone. Also, the\nAPI responses include some routes that may not be available for your instance.\n\nAlso note: The responses for this call can often be large (more than 1MB/patient in some scenarios) so\nresponse times to this call can vary. Please rate-limit this call to 20 calls/second and we recommend\nwaiting until after business hours if you are going to run this for all patients.\n\nFor a full sample response, please visit https://demo1.md-hq.com/custom/sample_data/extended_details.json\n", "security": [ { "basic_auth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": false, "description": "The ID of the patient.", "schema": { "type": "integer" } }, { "name": "anonymize", "in": "query", "required": false, "description": "The return values will strip PHI identifiers from the chart\nincluding: names, street-level addresses, telephone numbers (area codes will remain),\ndate-of-birth (year of birth will remain) and some questionnaire answers. Because ever\nclient has different questionnaires, you will want to make sure you further anonymize\nthe results if your questionnaires include requests for identifying information\n", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com /api/v1/patients/2/extended_details?anonymize=true\n" } ] } }, "/health_maintenance": { "get": { "operationId": "listHealthMaintenance", "tags": [ "Health Maintenance" ], "summary": "Get all Health Maintenance Trackers", "description": "Get all Health Maintenance Trackers from the Master Health Maintenance List.\n\nPlease note: All dates listed (creation times, date taken) are listed in UTC,\nso you'll want to adjust for your local timezone.\n", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Defaults to 100, but can be overridden (max is 100)." }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "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.\n" }, { "in": "query", "name": "include_specific_pt", "schema": { "type": "boolean" }, "description": "If set, returns specific patient data." } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/health_maintenance?limit=10&offset=0&include_specific_pt=1\n" } ] } }, "/health_maintenance/{health_maintenance_id}": { "get": { "operationId": "showHealthMaintenance", "tags": [ "Health Maintenance" ], "summary": "Get single Health Maintenance Tracker", "description": "Get single Health Maintenance Tracker from the Master Health Maintenance List", "parameters": [ { "in": "path", "name": "health_maintenance_id", "required": true, "schema": { "type": "integer" }, "description": "The ID of the health maintenance tracker to retrieve." } ], "responses": { "200": { "description": "Successful response\n\nClarification of returned values:\n\n“applies_to”: Either “All Patents” or the ID of the specific patent.\n\n“overrides”: Either NULL or the ID of the health maintenance tracker it overrides.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "sex": { "type": "string" }, "start_age": { "type": "integer" }, "end_age": { "type": "integer" }, "frequency": { "type": "string" }, "applies_to": { "type": "string" }, "overrides": { "type": "string" }, "icd_codes": { "type": "string" }, "created": { "type": "string" }, "addedby": { "type": "string" } } }, "examples": { "sample_response": { "value": { "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": "", "icd_codes": "", "created": "2019-03-30 02:01:34", "addedby": "18" } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/health_maintenance/2\n" } ] } }, "/laboratories": { "get": { "operationId": "listFacilities", "tags": [ "Facilities" ], "summary": "Get all Laboratory definitions", "description": "Get all Laboratory definitions from the Master Laboratories List.\n\nPlease note: All dates listed (creation times, date taken) are listed in UTC, \nso you'll want to adjust for your local timezone.\n", "parameters": [ { "in": "query", "name": "city", "schema": { "type": "string" }, "description": "Returns laboratory listings defined as being in this city." }, { "in": "query", "name": "state", "schema": { "type": "string" }, "description": "Returns laboratory listings defined as being in this state." }, { "in": "query", "name": "company-brand", "schema": { "type": "string" }, "description": "Returns laboratory listings of this brand (e.g., \"Quest\")." }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Upper bound on number of returned laboratory listings" }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "Lower bound on number of returned laboratory listings" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET \"https://subdomain.md-hq.com/api/v1/laboratories?limit=10&offset=0&city=Portland\"\n" } ] } }, "/patients/{patient_id}/partners/quest/orders": { "get": { "operationId": "listPartnerAppOrders", "tags": [ "Partner Applications" ], "summary": "Get all electronically-submitted orders to Quest Diagnostics for a patient", "description": "Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC,\nso you'll want to adjust for your local timezone.\n", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Defaults to 100, but can be overridden (max is 100)." }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "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.\n" }, { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient who orders apply to" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/partners/quest/orders\n" } ] } }, "/partners/quest/orders/{order_id}": { "get": { "operationId": "showPartnerAppOrder", "tags": [ "Partner Applications" ], "summary": "Get a single electronically-submitted order to Quest Diagnostics by the Quest order ID", "parameters": [ { "in": "path", "name": "order_id", "schema": { "type": "integer" }, "description": "ID of order to show" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/partners/quest/orders/2\n" } ] } }, "/partners/quest/requisition/{order_id}/content": { "get": { "operationId": "showPartnerAppOrderRaw", "tags": [ "Partner Applications" ], "summary": "Get the raw requisition document for an electronically-submitted order to Quest Diagnostics by the requisition ID", "parameters": [ { "in": "path", "name": "order_id", "schema": { "type": "integer" }, "description": "ID of order to show" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/partners/quest/requisition/3/content\n" } ] } }, "/patients/{pt_id}/estimates": { "get": { "operationId": "listAllPatientEstimates", "tags": [ "Patient Charges" ], "summary": "Get all estimated charges for a patient", "parameters": [ { "name": "pt_id", "in": "path", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "defaults to 100, but can be overridden (max is 100)." }, { "name": "offset", "in": "query", "schema": { "type": "integer" }, "description": "If the returned data indicates that there is more than the limit responses\n`(has_more: true)`, then it will offset the list to allow you to cycle through patient estimated charges.\n" }, { "name": "date_method", "in": "query", "schema": { "type": "string", "enum": [ "created", "transaction" ] }, "description": "If you're filtering by date range, should the range be calculated by date the\nestimated charge was created, or the recorded transaction date (manual date assigned to the estimated charge)? Valid\narguments are *created* and *transaction* (created is the default).\n" }, { "name": "start_date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "If this argument is included it will only show estimated charges from after this date (calculated by `date_method`)." }, { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "If this argument is included it will only show estimated charges from before this date (calculated by `date_method`)." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "description": { "type": "string", "enum": [ "patient_estimates" ] }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "patient_estimate" ] }, "id": { "type": "integer" }, "name": { "type": "string" }, "patient_id": { "type": "integer" }, "encounter_id": { "type": [ "integer", "null" ] }, "amount": { "type": "string" }, "quantity": { "type": "integer" }, "discount_multiplier": { "type": "integer" }, "charge_master_details": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "charge_definition" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "name_for_pt_portal": { "type": "string" }, "category": { "type": "string" }, "cpt_code": { "type": "string" }, "nicknames": { "type": "array", "items": { "type": "string" } }, "barcode_upc": { "type": "string" }, "description": { "type": "string" }, "retail": { "type": "string" }, "wholesale": { "type": "string" }, "is_supply": { "type": "boolean" }, "time_required": { "type": [ "string", "null" ] }, "is_taxable": { "type": "boolean" }, "tax_rate": { "type": "integer" }, "is_special": { "type": "boolean" }, "add_to_insurance_claims": { "type": "boolean" }, "inactive": { "type": "boolean" }, "addedby": { "type": "string" }, "created": { "type": "string", "format": "datetime" } } }, "billing_rules": { "type": "object", "properties": { "add_to_insurance_claim": { "type": "boolean" }, "cpt_code": { "type": "string" }, "cpt_modifiers": { "type": "string" }, "amt_billed_to_insurance": { "type": "string" }, "amt_paid_by_insurance": { "type": "string" }, "date_paid_by_insurance": { "type": [ "string", "null" ] }, "which_insurance_to_bill": { "type": [ "string", "null" ] }, "justifying_diagnoses": { "type": "array", "items": { "type": "string" } } } }, "location_identifier": { "type": [ "string", "null" ] }, "additional_details": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "owner_id": { "type": "integer" }, "addedby": { "type": "integer" }, "created": { "type": "string", "format": "datetime" }, "transaction_date": { "type": "string", "format": "date" }, "payment_details": { "type": [ "string", "null" ] }, "is_deleted": { "type": "boolean" }, "date_deleted": { "type": [ "string", "null" ], "format": "date" }, "expiration_date": { "type": [ "string", "null" ], "format": "date" }, "converted_tp_patient_charge_id": { "type": [ "string", "null" ] } } } } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/2/estimates?limit=100&offset=0&start_date=2024-01-01&end_date=2024-01-31\n" } ] } }, "/patients/{pt_id}/encounters/{encounter_id}/estimates": { "get": { "operationId": "listEncounterEstimates", "tags": [ "Patient Charges" ], "summary": "Get all estimated charges for a patient from a single encounter", "parameters": [ { "name": "pt_id", "in": "path", "schema": { "type": "integer" } }, { "name": "encounter_id", "in": "path", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "defaults to 100, but can be overridden (max is 100)." }, { "name": "offset", "in": "query", "schema": { "type": "integer" }, "description": "If the returned data indicates that there is more than the limit responses\n`(has_more: true)`, then it will offset the list to allow you to cycle through patient estimated charges.\n" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "description": { "type": "string", "enum": [ "encounter_estimates" ] }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "patient_estimate" ] }, "id": { "type": "integer" }, "name": { "type": "string" }, "patient_id": { "type": "integer" }, "encounter_id": { "type": [ "integer", "null" ] }, "amount": { "type": "string" }, "quantity": { "type": "integer" }, "discount_multiplier": { "type": "integer" }, "charge_master_details": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "charge_definition" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "name_for_pt_portal": { "type": "string" }, "category": { "type": "string" }, "cpt_code": { "type": "string" }, "nicknames": { "type": "array", "items": { "type": "string" } }, "barcode_upc": { "type": "string" }, "description": { "type": "string" }, "retail": { "type": "string" }, "wholesale": { "type": "string" }, "is_supply": { "type": "boolean" }, "time_required": { "type": [ "string", "null" ] }, "is_taxable": { "type": "boolean" }, "tax_rate": { "type": "integer" }, "is_special": { "type": "boolean" }, "add_to_insurance_claims": { "type": "boolean" }, "inactive": { "type": "boolean" }, "addedby": { "type": "string" }, "created": { "type": "string", "format": "datetime" } } }, "billing_rules": { "type": "object", "properties": { "add_to_insurance_claim": { "type": "boolean" }, "cpt_code": { "type": "string" }, "cpt_modifiers": { "type": "string" }, "amt_billed_to_insurance": { "type": "string" }, "amt_paid_by_insurance": { "type": "string" }, "date_paid_by_insurance": { "type": [ "string", "null" ] }, "which_insurance_to_bill": { "type": [ "string", "null" ] }, "justifying_diagnoses": { "type": "array", "items": { "type": "string" } } } }, "location_identifier": { "type": [ "string", "null" ] }, "additional_details": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "owner_id": { "type": "integer" }, "addedby": { "type": "integer" }, "created": { "type": "string", "format": "datetime" }, "transaction_date": { "type": "string", "format": "date" }, "payment_details": { "type": [ "string", "null" ] }, "is_deleted": { "type": "boolean" }, "date_deleted": { "type": [ "string", "null" ], "format": "date" }, "expiration_date": { "type": [ "string", "null" ], "format": "date" }, "converted_tp_patient_charge_id": { "type": [ "string", "null" ] } } } } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/2/encounters/423/estimates\n" } ] } }, "/patients/{pt_id}/estimates/{estimate_id}": { "get": { "operationId": "showPatientEstimate", "tags": [ "Patient Charges" ], "summary": "Get a specific patient estimated charge by ID", "parameters": [ { "name": "pt_id", "in": "path", "schema": { "type": "integer" } }, { "name": "estimate_id", "in": "path", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "patient_estimate" ] }, "id": { "type": "integer" }, "name": { "type": "string" }, "patient_id": { "type": "integer" }, "encounter_id": { "type": [ "integer", "null" ] }, "amount": { "type": "string" }, "quantity": { "type": "integer" }, "discount_multiplier": { "type": "integer" }, "charge_master_details": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "charge_definition" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "name_for_pt_portal": { "type": "string" }, "category": { "type": "string" }, "cpt_code": { "type": "string" }, "nicknames": { "type": "array", "items": { "type": "string" } }, "barcode_upc": { "type": "string" }, "description": { "type": "string" }, "retail": { "type": "string" }, "wholesale": { "type": "string" }, "is_supply": { "type": "boolean" }, "time_required": { "type": [ "string", "null" ] }, "is_taxable": { "type": "boolean" }, "tax_rate": { "type": "integer" }, "is_special": { "type": "boolean" }, "add_to_insurance_claims": { "type": "boolean" }, "inactive": { "type": "boolean" }, "addedby": { "type": "string" }, "created": { "type": "string", "format": "datetime" } } }, "billing_rules": { "type": "object", "properties": { "add_to_insurance_claim": { "type": "boolean" }, "cpt_code": { "type": "string" }, "cpt_modifiers": { "type": "string" }, "amt_billed_to_insurance": { "type": "string" }, "amt_paid_by_insurance": { "type": "string" }, "date_paid_by_insurance": { "type": [ "string", "null" ] }, "which_insurance_to_bill": { "type": [ "string", "null" ] }, "justifying_diagnoses": { "type": "array", "items": { "type": "string" } } } }, "location_identifier": { "type": [ "string", "null" ] }, "additional_details": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "owner_id": { "type": "integer" }, "addedby": { "type": "integer" }, "created": { "type": "string", "format": "datetime" }, "transaction_date": { "type": "string", "format": "date" }, "payment_details": { "type": [ "string", "null" ] }, "is_deleted": { "type": "boolean" }, "date_deleted": { "type": [ "string", "null" ], "format": "date" }, "expiration_date": { "type": [ "string", "null" ], "format": "date" }, "converted_tp_patient_charge_id": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/2/estimates/64\n" } ] } }, "/patients/{patient_id}/allergies": { "get": { "operationId": "listPatientAllergies", "tags": [ "Patient Allergies" ], "summary": "Get all allergies for a patient", "description": "Returns a list of all allergies recorded for a patient. Allergies can be one of three types:\n\n- **Medication** — A specific drug (sourced from the medication database). The `code_set` will be `ndc` and the `code` will be the drug's NDC code.\n- **Medication Class** — A class of medications (e.g. Penicillins). The `code_set` is generally `va-class` (VA drug classification) but other values are possible. The `code` will be the corresponding class code.\n- **General** — A non-medication allergen (e.g. Latex, Peanuts). The `code_set` and `code` will vary depending on how the allergen is coded in the system, and `code` may be null if no code is assigned.\n\nThe `scope` field indicates the breadth of the allergy:\n- `Specific` — The allergy is to the specific drug formulation only.\n- `All` — The allergy applies to all formulations of the drug.\n- `Class Members` — The allergy applies to all members of the medication class.\n- Empty string — Scope is not applicable (used for General type allergens).\n\nPlease note: The `created` timestamp is in UTC. Adjust for your local timezone as needed.\n", "parameters": [ { "in": "path", "name": "patient_id", "required": true, "schema": { "type": "integer" }, "description": "ID of patient" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "total_count": { "type": "integer", "description": "The number of allergy records returned" }, "has_more": { "type": "boolean", "description": "Whether there are additional results beyond those returned" }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the allergen. For Medication type, this is the generic name if scope is Specific, or the brand name if scope is All." }, "type": { "type": "string", "enum": [ "Medication", "Medication Class", "General" ], "description": "The category of allergen" }, "pt_id": { "type": "integer", "description": "The patient ID" }, "scope": { "type": "string", "enum": [ "Specific", "All", "Class Members", "" ], "description": "The breadth of the allergy reaction. Empty string for General type allergens." }, "code_set": { "type": "string", "description": "The coding system for the allergen code. Common values:\n- `ndc` — National Drug Code (Medication type)\n- `va-class` — VA Drug Classification (Medication Class type)\n- `Unsp` — Unspecified (default for General type when no code type is set)\n\nGeneral type allergens may have other code set values depending on how the allergen is configured.\n" }, "code": { "type": [ "string", "null" ], "description": "The allergen code in the specified code_set. May be null for General type allergens that have no assigned code." }, "reaction_type": { "type": "string", "description": "The type of reaction or reason for the allergy (e.g. Allergy, Adverse Reaction, Intolerance)" }, "comment": { "type": "string", "description": "Additional notes about the allergy" }, "addedby": { "type": "integer", "description": "The user ID of who added the allergy record" }, "created": { "type": "string", "description": "The UTC timestamp when the allergy was added" } } } } }, "required": [ "object", "total_count", "has_more", "data" ] } } } }, "400": { "description": "Bad Request — Invalid patient ID" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/allergies\n" } ] } }, "/patients/{patient_id}/documents": { "get": { "operationId": "listPatientDocuments", "tags": [ "Patient Documents" ], "summary": "Get All Documents for a Patient", "description": "Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC,\nso you'll want to adjust for your local timezone.\n", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "(optional) defaults to 100, but can be overridden (max is 100)" }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "(optional) If the returned data indicates that there are more responses than the\nlimit (has_more: true), then it will offset the list to allow you to cycle through\ndocuments.\n" }, { "in": "query", "name": "folder", "schema": { "type": "string" }, "description": "(optional) String (folder name). Limits results to a specific folder or \"tab.\"" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET \"https://subdomain.md-hq.com/api/v1/patients/2/documents\"\n" } ] }, "post": { "operationId": "createPatientDocument", "tags": [ "Patient Documents" ], "summary": "Add a document via the portal queue", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" }, { "in": "query", "name": "enqueue", "schema": { "type": "boolean" }, "description": "(true by default) If true, the system will insert the document into the active\npatient portal queue so that the clinic is notified and can review the proposed addition\n" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pt_id": { "type": "integer", "description": "(required) An integer identifier for the patient associated with the document." }, "mime_type": { "type": "string", "description": "(required) A string indicating the MIME type of the file.", "enum": [ "image/jpeg", "image/jpg", "image/gif", "image/png", "image/pngx", "image/bmp", "application/pdf", "application/x-pdf", "application/acrobat", "applications/vnd.pdf", "text/pdf", "text/x-pdf", "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/rtf", "application/vnd.ms-excel", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.ms-powerpoint", "application/vnd.openxmlformats-officedocument.presentationml.presentation", "application/vnd.ms-works", "audio/mpeg", "text/plain", "text/richtext", "text/csv", "text/html", "application/vnd.oasis.opendocument.text", "application/vnd.oasis.opendocument.graphics", "application/vnd.oasis.opendocument.presentation", "application/vnd.oasis.opendocument.chart" ] }, "name": { "type": "string", "description": "(required) A string to be used as the title of the document." }, "base64_content": { "type": "string", "format": "binary", "description": "(required) Binary data, encoded base64. Maximum file size is 16MB." }, "notes": { "type": "string", "description": "(optional, enqueue=true only) A string to provide highlights or context about the document submission request when document is being enqueued (if accepted from the queue, this will get added to the document `content` section)" }, "content": { "type": "string", "description": "(optional, enqueue=false only) A string to provide highlights or context about the document when document is being injected directly into the patient chart (enqueue=false)" }, "folder": { "type": "string", "description": "(optional) Which tab to file a document under. Argument is ignored if the `enqueue` parameter is set to true.", "enum": [ "Name of existing top-level document folder as configured in the EHR" ] }, "subfolder": { "type": "string", "description": "(optional) Name of subfolder to file document under. While this is a freetext valie, it is strongly recommended that standardized subfolders be used in each top-level folder to avoid creating large numbers of distict subfolders." }, "flag": { "type": "boolean", "description": "(optional) Set to true if this is a \"key document\" that will be accessibe on the first document tab of the patient dashboard" }, "requires_review": { "type": "integer", "description": "(optional) If set, the id of the provider who needs to review this document. Must be a non-deleted user ID or -1 if it should be assigned to all provider tasks lists" }, "dr_reviewer": { "type": "integer", "description": "(optional) If set, the id of the provider who signed off/reviewed this document. Set only if the document has been marked as reviewed" }, "dr_review_date": { "type": "string", "format": "date-time", "description": "(optional) If `dr_reviewer` is set, the date/time when the provider reviewed the document" }, "review_status": { "type": "integer", "description": "(optional) If the document still needs review by user specified by `requires_review`, set to 1" }, "result_code": { "type": "integer", "description": "(optional) If a document is known too represent abnormal findings for the patient, you can flag it as borderline or abnormal, which changes the way the document displays.\nValues: 0 = Normal, 1 = Borderline, 2 = Abnormal\n", "enum": [ 0, 1, 2 ] }, "follow_up_required_date": { "type": "string", "format": "date-time", "description": "(optional) The datetime that the system should notify clinician to re-review or follow up on document (creates a review task on this date)" }, "pt_notified": { "type": "integer", "description": "(optional) Specify whether the patient has already been notified about the contents of this document.\nValues: 1 = Notification not needed, 2 = Patient has been notified\n", "enum": [ 1, 2 ] }, "pt_notified_method": { "type": "string", "description": "(optional) If `pt_notified` is set to '2' (patient has been notified), you can specify how they were notified. You can submit any string <155 characters but we recommend specifying from this list where appropriate", "enum": [ "Patient Portal", "Phone", "Email", "Office Visit", "Telemed Visit", "House Call", "Mail" ] } } } } } }, "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"pt_id\":\"1\", \"mime_type\":\"image/png\", \"name\":\"UltrasoundImage042219\", \"notes\":\"Scanned April 22, 2019 at Acme Imaging Lab\", \"base64_content\":\"....\"}'-X POST https://subdomain.md-hq.com/api/v1/patients/1/documents\n" } ] } }, "/documents/{document_id}": { "get": { "operationId": "showPatientDocument", "tags": [ "Patient Documents" ], "summary": "Get a single document by document ID", "parameters": [ { "in": "path", "name": "document_id", "schema": { "type": "integer" }, "description": "ID of document" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/documents/4225\n" } ] } }, "/documents/{document_id}/content": { "get": { "operationId": "showPatientDocumentRaw", "tags": [ "Patient Documents" ], "summary": "Get the binary or raw file data by document ID", "parameters": [ { "in": "path", "name": "document_id", "schema": { "type": "integer" }, "description": "ID of document" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/documents/1337/content\n" } ] } }, "/documents/{document_id}/stream": { "get": { "operationId": "streamPatientDocument", "tags": [ "Patient Documents" ], "summary": "Stream the binary or raw file data by document ID", "parameters": [ { "in": "path", "name": "document_id", "schema": { "type": "integer" }, "description": "ID of document" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/documents/1337/stream\n" } ] } }, "/patients": { "get": { "operationId": "listPatients", "tags": [ "Patients" ], "summary": "Get all patients", "description": "Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC,\nso you'll want to adjust for your local timezone.\n", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "(optional) defaults to 100, but can be overridden (max is 100)" }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "If the returned data indicates that there is more than the limit\nresponses (has_more: true), then it will offset the list to allow you to cycle through\nlong patient list\n" }, { "in": "query", "name": "status", "schema": { "type": "boolean" }, "description": "If this parameter is set it will only include ACTIVE patients" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com /api/v1/patients\n" } ] }, "post": { "operationId": "createPatient", "tags": [ "Patients" ], "summary": "Create a new patient", "description": "Data: property-value key-pairs, including nested objects for address and insurance information (match the structure \nfrom the GET API call)\n\nNotes: At a minimum, you must provide a first name, last name, date of birth (preferred format is YYYY-MM-DD), and sex \n(must be M, F, or ?)\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "dob": { "type": "string", "description": "YYYY-MM-DD" }, "sex": { "type": "string", "description": "must be 'M', 'F', or '?'" }, "inactive": { "type": "string", "description": "Sets the patient status. Accepts the following values:\n\n| Value | Result |\n|---|---|\n| `\"prospective\"` or `\"-1\"` | Prospective patient |\n| `\"0\"`, empty, or omitted | Active patient (default) |\n| `\"inactive\"` or `\"1\"` | Inactive patient |\n| `\"deceased\"` or `\"dead\"` or `\"2\"` | Deceased patient |\n\n**Important — GET response behavior:**\n\nWhen reading patient data via GET, the `inactive` field is cast to a\nboolean rather than returning the original value. This means:\n\n| Stored status | `inactive` in GET | `patient_status_description` in GET |\n|---|---|---|\n| Prospective (`-1`) | `true` | `\"prospective\"` |\n| Active (`0`) | `false` | `\"active\"` |\n| Inactive (`1`) | `true` | `\"inactive\"` |\n| Deceased (`2`) | `true` | `\"deceased\"` |\n\nBecause `inactive` returns `true` for prospective, inactive, and deceased\npatients alike, you **must** use the `patient_status_description` field to\ndetermine the actual status. This is a known legacy serialization issue\nwhere the create/update and read representations differ.\n" } }, "required": [ "first_name", "last_name", "dob", "sex" ] } } } }, "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"first_name\":\"John\",\"last_name\":\"Doe\",\"dob\":\"1980-12-01\",\"sex\":\"M\"}' -X POST https://subdomain.md-hq.com/api/v1/patients\n" }, { "lang": "cURL", "label": "Create Prospective Patient", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"first_name\":\"Jane\",\"last_name\":\"Doe\",\"dob\":\"1990-01-15\",\"sex\":\"F\",\"inactive\":\"prospective\"}' -X POST https://subdomain.md-hq.com/api/v1/patients\n" } ] } }, "/patients/{patient_id}": { "get": { "operationId": "showPatient", "tags": [ "Patients" ], "summary": "Get a single patient (by ID)", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/2\n" } ] }, "patch": { "operationId": "updatePatient", "tags": [ "Patients" ], "summary": "Update a patient", "description": "Data: property-value key-pairs, including nested objects for address and insurance information (match the structure \nfrom the GET API call)\n", "parameters": [ { "in": "path", "name": "patient_id", "required": true, "schema": { "type": "integer" }, "description": "ID of the patient to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "dob": { "type": "string", "description": "YYYY-MM-DD" }, "sex": { "type": "string", "description": "must be 'M', 'F', or '?'" }, "inactive": { "type": "string", "description": "Sets the patient status. Accepts the following values:\n\n| Value | Result |\n|---|---|\n| `\"prospective\"` or `\"-1\"` | Prospective patient |\n| `\"0\"`, empty, or omitted | Active patient (default) |\n| `\"inactive\"` or `\"1\"` | Inactive patient |\n| `\"deceased\"` or `\"dead\"` or `\"2\"` | Deceased patient |\n\n**Important — GET response behavior:**\n\nWhen reading patient data via GET, the `inactive` field is cast to a\nboolean rather than returning the original value. This means:\n\n| Stored status | `inactive` in GET | `patient_status_description` in GET |\n|---|---|---|\n| Prospective (`-1`) | `true` | `\"prospective\"` |\n| Active (`0`) | `false` | `\"active\"` |\n| Inactive (`1`) | `true` | `\"inactive\"` |\n| Deceased (`2`) | `true` | `\"deceased\"` |\n\nBecause `inactive` returns `true` for prospective, inactive, and deceased\npatients alike, you **must** use the `patient_status_description` field to\ndetermine the actual status. This is a known legacy serialization issue\nwhere the create/update and read representations differ.\n" } } } } } }, "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"first_name\":\"Jonathan\",\"phone_home\":\"555-123-1234\"}' -X PATCH https://subdomain.md-hq.com/api/v1/patients/316\n" } ] }, "delete": { "operationId": "deletePatient", "tags": [ "Patients" ], "summary": "Archive a patient", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X DELETE https://subdomain.md-hq.com/api/v1/patients/316\n" } ] } }, "/patients/search": { "get": { "operationId": "searchPatients", "tags": [ "Patients" ], "summary": "Find all patients matching criteria", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "defaults to 100, but can be overridden (max is 100)" }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "If the returned data indicates that there is more than the limit\nresponses (has_more: true), then it will offset the list to allow you to cycle through\nlong patient list\n" }, { "in": "query", "name": "last_name", "schema": { "type": "string" }, "description": "Match patients with given last name. Allows wildcard: smith%\nwill match “Smith”,”Smithson”,”Simthe” etc)\n" }, { "in": "query", "name": "first_name", "schema": { "type": "string" }, "description": "Match patients with given first name Allows wildcard: ben%\nwill match “Ben”,”Benjamin”,”Bennett” etc)\n" }, { "in": "query", "name": "email", "schema": { "type": "string" }, "description": "Match patients with given email as their primary or secondary\naddress Allows wildcard: %@gmail.com will match all patients with Gmail addresses\n" }, { "in": "query", "name": "username", "schema": { "type": "string" }, "description": "Match patients with given patient portal username" }, { "in": "query", "name": "dob", "schema": { "type": "string" }, "description": "Match patients with given date of birth (preferred format is yyyy-mmdd). No wildcards allowed" }, { "in": "query", "name": "timezone", "schema": { "type": "string" }, "description": "Match patients with given timezone (Must be a canonical timezone https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "example": "America/New_York" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/search?first_name=John%&last_name=Doe%&dob=1980-12-01\n" } ] } }, "/patients/{patient_id}/emails/send": { "post": { "operationId": "sendPatientEmail", "parameters": [ { "in": "path", "name": "patient_id", "required": true, "schema": { "type": "integer" }, "description": "ID of the patient to send email to" } ], "tags": [ "Patient Emails" ], "summary": "Send an email to a patient's primary email address", "description": "This endpoint allows you to send an email in the same format as other system-generated emails (with your logo at the \ntop and practice information at the bottom). This will look identical to emails sent to patients by clicking on their \nemail address from the Patient Information block in the EMR.\n\nPlease note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC,\nso you'll want to adjust for your local timezone.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject of email to be sent" }, "body": { "type": "string", "description": "Body of email to be sent" }, "reply-to": { "type": "string", "description": "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)." } }, "required": [ "subject", "body", "reply-to" ] } } } }, "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\\\"subject\\\": \\\"Thanks for coming in!\\\",\\\"body\\\":\\\"It was great to see you, please give us a call if you have any questions about your treatment plan.\\\",\\\"replyto\\\":\\\"support@cer.bo\\\"}' -X POST https://subdomain.md-hq.com/api/v1/patients/1/emails/send\n" } ] } }, "/patients/{patient_id}/laboratories": { "get": { "operationId": "listPatientFacilities", "parameters": [ { "in": "path", "name": "patient_id", "required": true, "schema": { "type": "integer" }, "description": "ID of the patient" } ], "tags": [ "Patient Facilities/Specialists" ], "summary": "Get all laboratories for a patient", "description": "Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for\nyour local timezone.\n", "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/laboratories\n" } ] }, "post": { "operationId": "createPatientFacility", "parameters": [ { "in": "path", "name": "patient_id", "required": true, "schema": { "type": "integer" }, "description": "ID of the patient" } ], "tags": [ "Patient Facilities/Specialists" ], "summary": "Add a preferred laboratory for a patient", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "laboratory_id": { "type": "integer", "description": "An integer, the laboratory ID to add. See the \"Facility Endpoints\" documentation \nfor how to find the ID in the master laboratories database\n" }, "priority_order": { "type": "integer", "description": "An integer representing where in the patient's laboratories list this entry should\ngo (lowest number is considered the first/preferred listing). If null, the system will look at \nset_as_primary instead.\n" }, "set_as_primary": { "type": "boolean", "description": "A boolean value representing if this should be added as the patient's new\npreferred listing, or just added to the bottom of the list. If priority_order \nis set, this argument will be ignored.\n" }, "note": { "type": "string", "description": "A string, 255 character max" } }, "required": [ "laboratory_id" ] } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X POST https://subdomain.md-hq.com/api/v1/patients/1/laboratories --data '{\\\"laboratory_id\\\":3, \\\"set_as_primary\\\": false, \\\"note\\\": \\\"Just add to the bottom of the list/not priority\\\"}'\n" } ] } }, "/patients/{patient_id}/laboratories/{patient_laboratory_id}": { "delete": { "operationId": "deletePatientFacility", "parameters": [ { "in": "path", "name": "patient_id", "required": true, "schema": { "type": "integer" }, "description": "ID of the patient" }, { "in": "path", "name": "patient_laboratory_id", "required": true, "schema": { "type": "integer" }, "description": "ID of the patient laboratory association" } ], "tags": [ "Patient Facilities/Specialists" ], "summary": "Delete patient laboratory", "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X DELETE https://subdomain.md-hq.com/api/v1/patients/1/laboratories/22\n" } ] } }, "/patients/{patient_id}/specialists": { "get": { "operationId": "listPatientSpecialists", "tags": [ "Patient Facilities/Specialists" ], "summary": "Get patient's specialists", "description": "Returns a list of specialists associated with a patient, ordered by priority.\nEach specialist includes full contact details and specialty information.\n", "parameters": [ { "name": "patient_id", "in": "path", "required": true, "description": "The patient ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "total_count": { "type": "integer", "description": "Number of specialists returned" }, "has_more": { "type": "boolean", "example": false, "description": "Always false (no pagination)" }, "data": { "type": "array", "description": "Array of patient-specialist association objects", "items": { "type": "object", "properties": { "object": { "type": "string", "example": "patient_specialist" }, "id": { "type": "integer", "description": "Patient-specialist association ID" }, "specialist_id": { "type": "integer", "description": "ID in the master specialists database" }, "priority_order": { "type": "integer", "description": "Position in patient's specialist list (lower = higher priority)" }, "note": { "type": [ "string", "null" ], "description": "Optional note about this specialist for the patient" }, "specialist_details": { "type": "object", "description": "Full specialist information", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "description": "Specialist name" }, "specialty": { "type": [ "string", "null" ], "description": "Medical specialty" }, "phone": { "type": [ "string", "null" ] }, "fax": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "address1": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] } } }, "created": { "type": "string", "format": "date-time", "description": "When this association was created (UTC)" }, "addedby": { "type": "integer", "description": "User ID who created this association" } } } } } } } } }, "400": { "description": "Bad Request - Invalid patient ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid patient ID passed" } } } } } }, "500": { "description": "Internal Server Error" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/3/specialists\n" } ] }, "post": { "operationId": "createPatientSpecialist", "tags": [ "Patient Facilities/Specialists" ], "summary": "Add a specialist to a patient", "description": "Links a specialist from the master specialists database to a patient.\nUse either `priority_order` (explicit position) or `set_as_primary` (add to top/bottom) to control placement.\n", "parameters": [ { "name": "patient_id", "in": "path", "required": true, "description": "The patient ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "description": "Specialist association data", "content": { "application/json": { "schema": { "type": "object", "required": [ "specialist_id" ], "properties": { "specialist_id": { "type": "integer", "description": "The specialist ID from the master specialists database.\nUse the facilities/specialists endpoints to find valid IDs.\n" }, "priority_order": { "type": "integer", "description": "Position in the patient's specialist list (lower = higher priority).\nIf provided, `set_as_primary` is ignored.\n" }, "set_as_primary": { "type": "boolean", "description": "If true, adds to top of list (priority). If false, adds to bottom.\nOnly used when `priority_order` is not provided.\n" }, "note": { "type": "string", "maxLength": 255, "description": "Optional note about this specialist for the patient (max 255 characters)" } } }, "examples": { "with_priority": { "summary": "Using explicit priority order", "value": { "specialist_id": 12, "priority_order": 0, "note": "Primary cardiologist" } }, "with_set_as_primary": { "summary": "Using set_as_primary flag", "value": { "specialist_id": 12, "set_as_primary": true, "note": "Primary cardiologist" } } } } } }, "responses": { "200": { "description": "OK - Returns the created patient-specialist association", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Patient-specialist association ID" }, "specialist_id": { "type": "integer" }, "priority_order": { "type": "integer" }, "note": { "type": [ "string", "null" ] }, "created": { "type": "string", "format": "date-time" } } } } } }, "409": { "description": "Conflict - Specialist already linked to patient", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "example": "conflict" }, "message": { "type": "string", "example": "Unable to link patient to specialist: That specialist already exists in this patient's preferred specialists" } } } } } } } }, "500": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "example": "validation_error" }, "message": { "type": "string" } } } } } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" \\\n -H \"Content-Type: application/json\" \\\n -X POST https://subdomain.md-hq.com/api/v1/patients/3/specialists \\\n -d '{\"specialist_id\":12,\"set_as_primary\":true,\"note\":\"Primary cardiologist\"}'\n" } ] } }, "/patients/{patient_id}/specialists/{patient_specialist_id}": { "delete": { "operationId": "deletePatientSpecialist", "tags": [ "Patient Facilities/Specialists" ], "summary": "Remove a specialist from a patient", "description": "Removes a specialist association from a patient. This does not delete the specialist\nfrom the master database, only the link to this patient.\n", "parameters": [ { "name": "patient_id", "in": "path", "required": true, "description": "The patient ID", "schema": { "type": "integer" } }, { "name": "patient_specialist_id", "in": "path", "required": true, "description": "The patient-specialist association ID (not the specialist ID)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK - Specialist removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Patient specialist disconnected successfully" } } } } } }, "400": { "description": "Bad Request - Invalid association or patient mismatch", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "example": "argument_error" }, "message": { "type": "string", "example": "Invalid patient specialist" } } } } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "example": "permission_error" }, "message": { "type": "string", "example": "This API account does not have permission to delete patient facilities" } } } } } } } }, "500": { "description": "Internal Server Error" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" \\\n -X DELETE https://subdomain.md-hq.com/api/v1/patients/3/specialists/45\n" } ] } }, "/patients/{patient_id}/pharmacies": { "get": { "operationId": "listPatientPharmacies", "tags": [ "Patient Facilities/Specialists" ], "summary": "Get patient's pharmacies", "description": "Returns a list of pharmacies associated with a patient, ordered by priority.\nEach pharmacy includes full contact details and NCPDP identifier.\n\nNote: Creating and deleting patient pharmacy associations is not currently supported\nvia the API (returns 501 Not Implemented).\n", "parameters": [ { "name": "patient_id", "in": "path", "required": true, "description": "The patient ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "total_count": { "type": "integer", "description": "Number of pharmacies returned" }, "has_more": { "type": "boolean", "example": false, "description": "Always false (no pagination)" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "example": "patient_pharmacy" }, "id": { "type": "integer", "description": "Patient-pharmacy association ID" }, "pharmacy_id": { "type": "integer", "description": "ID in the master pharmacies database" }, "priority_order": { "type": "integer", "description": "Position in patient's pharmacy list (lower = higher priority)" }, "note": { "type": "string", "description": "Optional note about this pharmacy for the patient" }, "pharmacy_details": { "type": "object", "description": "Full pharmacy information", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "description": "Pharmacy name" }, "company-brand": { "type": "string", "description": "Company or brand name" }, "ncpdp_id": { "type": [ "string", "null" ], "description": "NCPDP (National Council for Prescription Drug Programs) identifier" }, "address1": { "type": [ "string", "null" ] }, "address2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "phone-alt": { "type": [ "string", "null" ] }, "fax": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "facility-hours": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "practice-favorite": { "type": "boolean", "description": "Whether this pharmacy is a practice favorite" }, "addedby": { "type": "integer" }, "created": { "type": "string", "format": "date-time" } } }, "created": { "type": "string", "format": "date-time", "description": "When this association was created (UTC)" }, "addedby": { "type": "integer", "description": "User ID who created this association" } } } } } } } } }, "400": { "description": "Bad Request - Invalid patient ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid patient ID passed" } } } } } }, "500": { "description": "Internal Server Error" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/3/pharmacies\n" } ] } }, "/pt_notes": { "get": { "operationId": "listPatientNotes", "tags": [ "Patient Free-Text Notes" ], "summary": "Get all available patient free-text note types", "description": "Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for\nyour local timezone.\n", "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/pt_notes\n" } ] } }, "/patients/{patient_id}/pt_notes": { "get": { "operationId": "listAllPatientNotes", "tags": [ "Patient Free-Text Notes" ], "summary": "Get all free-text notes for a patient", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/pt_notes\n" } ] } }, "/patients/{patient_id}/pt_notes/{pt_note_type_id}": { "get": { "operationId": "showPatientNote", "tags": [ "Patient Free-Text Notes" ], "summary": "Get free-text notes of one type for a patient", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" }, { "in": "path", "name": "pt_note_type_id", "schema": { "type": "integer" }, "description": "ID of note type" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/pt_notes/1\n" } ] }, "post": { "operationId": "updatePatientNote", "tags": [ "Patient Free-Text Notes" ], "summary": "Edit a specific free-text note for a patient", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" }, { "in": "path", "name": "pt_note_type_id", "schema": { "type": "integer" }, "description": "ID of note type" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "description": "The new free-text note value" } }, "required": [ "note" ] } } } }, "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X POST https://subdomain.md-hq.com/api/v1/patients/1/pt_notes/1 -H \\\"Content-Type: application/json\\\" --data \\\"{'note':'This a test note'}\\\"\n" } ] } }, "/patients/{patient_id}/images": { "get": { "operationId": "listPatientImages", "tags": [ "Patient Images" ], "summary": "Get all images for a patient", "description": "Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for\nyour local timezone.\n", "parameters": [ { "in": "path", "name": "patient_id", "required": true, "schema": { "type": "integer" }, "description": "ID of patient" }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Defaults to 100, but can be overridden (max is 100)." }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "If the returned data indicates that there are more responses than the limit \n(has_more: true), then it will offset the list to allow you to cycle through documents.\n" }, { "in": "query", "name": "photo_type", "schema": { "type": "string" }, "description": "String (either “personal” or “medical”). If left blank, both types will be returned." } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/images?photo_type=personal\n" } ] }, "post": { "operationId": "createPatientImage", "tags": [ "Patient Images" ], "summary": "Add a patient personal image via the portal queue", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pt_id": { "type": "integer", "description": "An integer identifier for the patient associated with the document." }, "mime_type": { "type": "string", "description": "A string indicating the MIME type of the file.\n\nValid MIME types:\nimage/jpeg\nimage/jpg\nimage/gif\nimage/png\nimage/pngx\n" }, "base64_content": { "type": "string", "format": "binary", "description": "Binary data, encoded base64. Maximum file size is 16MB." } }, "required": [ "pt_id", "mime_type", "base64_content" ] } } } }, "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"pt_id\":\"1\", \"mime_type\":\"image/png\", \"base64_content\":\".…\"}' -X POST https://subdomain.md-hq.com/api/v1/patients/1/images \n" } ] } }, "/patients/{patient_id}/images/{image_id}": { "get": { "operationId": "showPatientImage", "tags": [ "Patient Images" ], "summary": "Get a single patient image by image ID", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" }, { "in": "path", "name": "image_id", "schema": { "type": "integer" }, "description": "ID of image" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/images/54\n" } ] } }, "/patients/{patient_id}/images/{image_id}/content": { "get": { "operationId": "showPatientImageContent", "tags": [ "Patient Images" ], "summary": "Get the binary or raw file data by image ID", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" }, { "in": "path", "name": "image_id", "schema": { "type": "integer" }, "description": "ID of image" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/images/54/content\n" } ] } }, "/patients/{patient_id}/images/{image_id}/stream": { "get": { "operationId": "streamPatientImage", "tags": [ "Patient Images" ], "summary": "Stream the binary or raw file data by image ID", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" }, { "in": "path", "name": "image_id", "schema": { "type": "integer" }, "description": "ID of image" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/images/54/stream\n" } ] } }, "/patients/{patient_id}/health_maintenance": { "get": { "operationId": "showPatientHealthMaintenance", "tags": [ "Patient Health Maintenance" ], "summary": "Get all health maintenance readings for a patient", "description": "Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for\nyour local timezone.\n", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/health_maintenance\n" } ] } }, "/patients/{patient_id}/health_maintenance/{health_maintenance_id}": { "post": { "operationId": "createPatientHealthMaintenance", "tags": [ "Patient Health Maintenance" ], "summary": "Add a health maintenance reading for a patient", "parameters": [ { "name": "patient_id", "in": "path", "description": "ID of patient", "required": true, "schema": { "type": "integer" } }, { "name": "health_maintenance_id", "in": "path", "description": "ID of health maintenance entry\n\n*See “HEALTH MAINTENANCE ENDPOINTS” documentation to get \ndefinitions from the master health maintenance trackers list\n", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "description": "A string specifying the date of the health maintenance tracker." }, "notes": { "type": "integer", "description": "A string" } }, "required": [ "date" ] } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"date\":\"11/10/2002\", \"notes\":\"Zoom appointment\"}' -X POST https://subdomain.md-hq.com/api/v1/patients/1/health_maintenance/14 \n" } ] } }, "/patients/{patient_id}/invoices": { "get": { "operationId": "listPatientInvoices", "tags": [ "Patient Invoices" ], "summary": "Get All Invoices for a Patient", "description": "Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for\nyour local timezone.\n", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Defaults to 100, but can be overridden (max is 100)." }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "If the returned data indicates that there are more responses than the limit \n(has_more: true), then it will offset the list to allow you to cycle through invoices.\n" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/2/invoices?limit=10\n" } ] } }, "/invoices/{invoice_id}": { "get": { "operationId": "showPatientInvoice", "tags": [ "Patient Invoices" ], "summary": "Get a single invoice by invoice ID", "parameters": [ { "in": "path", "name": "invoice_id", "schema": { "type": "integer" }, "description": "ID of invoice" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/invoices/4225\n" } ] } }, "/patients/{patient_id}/orders": { "get": { "operationId": "listPatientOrders", "tags": [ "Patient Orders" ], "summary": "Get All Orders for a Patient", "description": "Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for\nyour local timezone.\n", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET \"https://subdomain.md-hq.com/api/v1/patients/2/orders\"\n" } ] } }, "/patients/{patient_id}/orders/{order_id}": { "get": { "operationId": "showPatientOrder", "tags": [ "Patient Orders" ], "summary": "Get a single order by order ID", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" }, { "in": "path", "name": "order_id", "schema": { "type": "integer" }, "description": "ID of patient" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1//patients/343/orders/1462\n" } ] } }, "/patients/{patient_id}/pmh": { "get": { "operationId": "listPatientPastMedicalHistory", "tags": [ "Patient Past Medical History" ], "summary": "Get the Past Medical History for a patient", "description": "Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for\nyour local timezone.\n", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "total_count": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "pmh" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "display_name": { "type": "string", "description": "this will be the “PMH Display Name” if set under Admin > Manage > Diagnostic Codes" }, "icd_version": { "type": "string" }, "code": { "type": "string" }, "problem_status": { "type": "string", "description": "active, chronic active, inactive, chronic inactive" }, "addedby": { "type": "string" }, "created": { "type": "string" }, "encounter_id": { "type": "integer" }, "url_encounter": { "type": "integer" } } } } }, "required": [ "object", "total_count", "data" ] } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/pmh\n" } ] } }, "/patients/{pt_id}/portal/enqueued": { "get": { "operationId": "showPortalRequests", "tags": [ "Patient Portal" ], "summary": "Get all enqueued portal requests for a patient", "description": "Please note: All dates listed are listed in UTC, so you'll want to adjust for your local timezone. Also, the\nAPI responses include some routes that may not be available for your instance. For the most part adding\nto the patient portal is going to be made through message-type specific endpoints (i.e. the\n/patients/:pt_id/questionnairesendpoint or the/patients/:pt_id/rxs endpoint) and the documentation for\nthose posts are listed alongside other related calls. However, if you're just looking to summarize or\nmanage posts that are already in queue (before they've been dismissed) you can use the calls below:\n", "parameters": [ { "in": "path", "name": "pt_id", "schema": { "type": "integer" }, "description": "ID of patient" }, { "in": "query", "name": "request_type", "schema": { "type": "string" }, "description": "return only specific types of requests" }, { "in": "query", "name": "request_status", "schema": { "type": "string" }, "description": "return requests of a specific status (defaults to “pending”). Accepted values are “pending”, “accepted”, “rejected”, “any”" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/portal/enqueued\n" } ] } }, "/patients/{pt_id}/portal/enqueued/{queue_request_id}": { "delete": { "operationId": "deletePortalRequest", "tags": [ "Patient Portal" ], "summary": "Delete/remove an enqueued request", "description": "All API-supported DELETE commands are “soft-deletes” so the data remains available but\nhidden. The time and API-user-identifier are both recorded automatically\n", "parameters": [ { "in": "path", "name": "pt_id", "schema": { "type": "integer" }, "description": "ID of patient" }, { "in": "path", "name": "queue_request_id", "schema": { "type": "integer" }, "description": "ID of queued request" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X DELETE https://subdomain.md-hq.com/api/v1/patients/1/portal/enqueued/27\n" } ] } }, "/patients/{pt_id}/portal/invite": { "post": { "operationId": "inviteToPortal", "tags": [ "Patient Portal" ], "summary": "Trigger an email invitation to join portal (or reset password)", "description": "This will try to send an email to the patient's primary email address with an encrypted\nlink. The text and subject of this email will be the same as the settings that you use when\ninviting patients from inside the EMR. \n", "parameters": [ { "in": "path", "name": "pt_id", "schema": { "type": "integer" }, "description": "ID of patient" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X POST https://ben:password@sandbox.md-hq.com/api/v1/patients/221/portal/invite\n" } ] } }, "/patients/portal/validate_credentials": { "post": { "operationId": "validatePortalCredentials", "tags": [ "Patient Portal" ], "summary": "Validate patient portal login credentials", "description": "If the credentials are valid, this will return the matching patient's details", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "The patient's username that they use to login to your patient portal" }, "password": { "type": "string", "description": "The patient's password that they use to login to your patient portal" } }, "required": [ "username", "password" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean" }, "message": { "type": "string" }, "patient_details": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email_address": { "type": "string" }, "status": { "type": "string" } } } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -data '{“username”:”support@md-hq.com”,”password”:”password”}' -X POST https://ben:password@sandbox.md-hq.com/api/v1/patients/portal/validate_credentials\n" } ] } }, "/patients/{patient_id}/rxs": { "get": { "operationId": "listPatientPrescriptions", "tags": [ "Patient Prescriptions" ], "summary": "Get All Prescriptions for a Patient", "description": "Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC,\nso you'll want to adjust for your local timezone. If you want to manage underlying drug definitions\nplease use the /v1/drugs endpoints.\n", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/2/rxs\n" } ] }, "post": { "operationId": "queuePatientPrescription", "tags": [ "Patient Prescriptions" ], "summary": "Post a new patient prescription via the portal queue", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" }, { "in": "query", "name": "enqueue", "schema": { "type": "boolean" }, "description": "(true by default) If true, the system will insert the drug into the active patient\nportal queue so that the clinic is notified and can review the proposed addition. This\nreplicates the functionality of the patient portal queue.\n" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "drug_id": { "type": "integer", "description": "An integer identifier for a drug as returned from a /v1/drugs/search/:term query." }, "notes": { "type": "string" } }, "required": [ "drug_id" ] } } } }, "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"drug_id\": \"214322\",\"notes\":\"Takes in the AM with food and water\"}' -X POST https://subdomain.md-hq.com/api/v1/patients/1/rxs?enqueue=true\n" } ] } }, "/patients/{patient_id}/rxs/{medication_prescribed_id}": { "get": { "operationId": "showPatientPrescription", "tags": [ "Patient Prescriptions" ], "summary": "Get a Single Patient Prescription Details", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" }, { "in": "path", "name": "medication_prescribed_id", "schema": { "type": "integer" }, "description": "ID of prescribed medication" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/rxs/4225\n" } ] } }, "/patients/{pt_id}/rxs/{pt_rx_id}/discontinue": { "patch": { "operationId": "discontinuePatientPrescription", "tags": [ "Patient Prescriptions" ], "summary": "Discontinue a patient medication", "description": "Marks a patient's medication prescription as discontinued. This does not delete the record -\nthe medication will remain in the patient's history with a discontinued status.\n", "parameters": [ { "name": "pt_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the patient" }, { "name": "pt_rx_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the patient's medication prescription to discontinue" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "discontinued_reason" ], "properties": { "discontinued_date": { "type": "string", "format": "date-time", "description": "Date and time when the medication was discontinued.\nIf not provided, defaults to the current date/time.\n", "example": "2024-01-15T14:30:00Z" }, "discontinued_reason": { "type": "string", "maxLength": 500, "description": "Reason for discontinuing the medication (required)", "example": "Patient experiencing adverse side effects" } } } } } }, "responses": { "200": { "description": "Medication successfully discontinued", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "medication_prescribed" ] }, "id": { "type": "integer", "description": "ID of the discontinued prescription" }, "drug_id": { "type": "integer" }, "drug_name": { "type": "string" }, "status": { "type": "string", "enum": [ "Discontinued" ] }, "discontinued_date": { "type": "string", "format": "date-time" }, "discontinued_reason": { "type": "string" } } } } } }, "400": { "description": "Bad Request - Invalid patient ID or prescription ID" }, "500": { "description": "Server Error" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" \\\n --data '{\"discontinued_reason\":\"Patient experiencing adverse side effects\",\"discontinued_date\":\"2024-01-15T14:30:00Z\"}' \\\n -X PATCH https://subdomain.md-hq.com/api/v1/patients/123/rxs/456/discontinue\n" } ] } }, "/patients/{patient_id}/rxs/refill": { "post": { "operationId": "refillPatientPrescription", "tags": [ "Patient Prescriptions" ], "summary": "Post a medication prescription refill via the portal queue", "parameters": [ { "in": "path", "name": "patient_id", "schema": { "type": "integer" }, "description": "ID of patient" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "original_prescription_id": { "type": "integer", "description": "An integer identifier for an existing prescription for this patient as returned from a /v1/patients/:patient_id/rxs GET query." }, "notes": { "type": "string" }, "agreed_to_terms": { "type": "string", "description": "A string value representing agreement to terms. If not set, defaults to \"No terms agreed to\"." } }, "required": [ "original_prescription_id" ] } } } }, "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"original_prescription_id\":\"2112\",\"notes\":\"Takes in the AM with food and water\", \"agreed_to_terms\":\"I agree\"}' -X POST https://subdomain.md-hq.com/api/v1/patients/1/rxs/refill\n" } ] } }, "/patients/subscriptions": { "get": { "operationId": "listPatientSubscriptions", "tags": [ "Patient Subscriptions" ], "summary": "Get All Subscriptions", "description": "**Note:** This endpoint requires a compatible merchant services integration to be activated on the account.\nAccounts without an active merchant services integration will receive a `403 Forbidden` response.\n\nPlease note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for\nyour local timezone.\n", "parameters": [ { "name": "limit", "in": "query", "description": "Number of results returned. Default (and maximum) is 100.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Used for looping through the dataset. Default is 0.", "schema": { "type": "integer" } }, { "name": "include_deleted", "in": "query", "description": "Returns deleted and current subscriptions if set to true. Default is false.", "schema": { "type": "boolean" } }, { "name": "schedule_frequency", "in": "query", "description": "If set to monthly/weekly/annually, it will only return subscriptions billing at that frequency.", "schema": { "type": "string", "enum": [ "monthly", "weekly", "annually" ] } }, { "name": "subscription_charge_id", "in": "query", "description": "ID of a specific charge associated with a subscription-type. If set, it will only return that type of subscription.", "schema": { "type": "string" } }, { "name": "charge_owner_user_id", "in": "query", "description": "ID of a Cerbo user that gets 'credit' for that subscription. If set, it will only return 'their' subscriptions.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" }, "403": { "description": "A compatible merchant services integration is not activated on the account." } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -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\n" } ] } }, "/patients/{patient_id}/subscriptions": { "get": { "operationId": "showPatientSubscriptions", "tags": [ "Patient Subscriptions" ], "summary": "Get All Subscriptions for a Single Patient", "description": "**Note:** This endpoint requires a compatible merchant services integration to be activated on the account.\nAccounts without an active merchant services integration will receive a `403 Forbidden` response.\n", "parameters": [ { "name": "patient_id", "in": "path", "description": "ID of patient", "schema": { "type": "integer" } }, { "name": "include_deleted", "in": "query", "description": "False by default. Returns deleted and current subscriptions if set to true.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "- A subscription is considered delinquent if it is not deleted and the most recent charge attempted is at least one day old, is not voided, and has no credit allocated to it.\n\n- charge_runs_on return value depends on the schedule_frequency of the subscription. Day of the week for weekly, day of month for monthly, month and day (MM/DD) for annually.\n\n- success_attempts indicates the number of times the subscription charge was successfully applied to the patient's account (not the number of times it was paid)\n\n- fail_attempts indicates the number of times the subscription charge was unsuccessfully applied to the patient's account (not the number of times payment failed)\n\n| schedule_frequency | charge_runs_on |\n|--------------------|-----------------------------------------------|\n| Weekly | Day of the week (e.g., Monday, Friday, etc.) |\n| Monthly | Day of the month (e.g., 1, 15, etc.) |\n| Annually | DD/MM day of the year (e.g., 02/07, 10/22, etc.) |\n" }, "400": { "description": "Bad Request" }, "403": { "description": "A compatible merchant services integration is not activated on the account." } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1540/subscriptions?include_deleted=true\n" } ] } }, "/patients/{patient_id}/supplements": { "get": { "operationId": "listPatientSupplements", "tags": [ "Patient Supplements" ], "summary": "Get All Supplements for a Patient", "description": "Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC, so you'll \nwant to adjust for your local timezone. If you want to manage underlying supplement definitions please use the /v1/\nsupplements endpoints.\n", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "- The prescribing_details sub-object has an unreliable structure, so it's entirely possible that it will contain/omit specific properties. Make sure you have a handler for cases where this data is missing in your application.\n" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/2/supplements\n" } ] }, "post": { "operationId": "queuePatientSupplement", "tags": [ "Patient Supplements" ], "summary": "Post a new patient supplement via the portal queue", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } }, { "name": "enqueue", "in": "query", "schema": { "type": "boolean" }, "description": "(true by default) If true, the system will insert the supplement into the active\npatient portal queue so that the clinic is notified and can review the proposed addition.\nThis replicates the functionality of the patient portal queue.\n" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "supplement_id": { "type": "integer", "description": "An integer identifier for a supplement as returned from a /v1/supplements/search/:term query." }, "notes": { "type": "string" } }, "required": [ "supplement_id" ] } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"supplement_id\": \"242\",\"notes\":\"Takes in the AM with food and water\"}' -X POST https://subdomain.md-hq.com/api/v1/patients/1/supplements?enqueue=true\n" } ] } }, "/patients/{patient_id}/supplements/{supplement_prescribed_id}": { "get": { "operationId": "showPatientSupplement", "tags": [ "Patient Supplements" ], "summary": "Get a single patient supplement details", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } }, { "name": "supplement_prescribed_id", "in": "path", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/supplements/325\n" } ] } }, "/patients/{pt_id}/supplements/{pt_plan_other_id}/discontinue": { "patch": { "operationId": "discontinuePatientSupplement", "tags": [ "Patient Supplements" ], "summary": "Discontinue a patient supplement", "description": "Marks a patient's supplement prescription as discontinued. This does not delete the record -\nthe supplement will remain in the patient's history with a discontinued status.\n", "parameters": [ { "name": "pt_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the patient" }, { "name": "pt_plan_other_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the patient's supplement prescription to discontinue" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "discontinued_date": { "type": "string", "format": "date-time", "description": "Date and time when the supplement was discontinued.\nIf not provided, defaults to the current date/time.\n", "example": "2024-01-15T14:30:00Z" }, "discontinued_note": { "type": "string", "description": "Reason for discontinuing the supplement", "example": "No longer needed per provider recommendation" } } } } } }, "responses": { "200": { "description": "Supplement successfully discontinued. Returns the full supplement object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "description": "The plan type (e.g., \"supplement\", \"supplement_otc\")", "example": "supplement" }, "id": { "type": "integer", "description": "ID of the patient's supplement prescription" }, "name": { "type": "string", "description": "Name of the supplement" }, "plan_type": { "type": "string", "description": "Type classification of the plan" }, "plan_definition": { "type": "object", "description": "Core definition of the supplement", "properties": { "name": { "type": "string" }, "id": { "type": "integer" }, "nicknames": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "class": { "type": [ "string", "null" ] }, "disabled": { "type": "boolean" } } }, "prescribing_details": { "type": [ "object", "null" ], "description": "Details about how the supplement was prescribed", "properties": { "dose": { "type": "string" }, "frequency": { "type": "string" }, "start_date": { "type": "string" }, "discontinued": { "type": "string", "enum": [ "1" ] }, "discontinued_note": { "type": "string" }, "discontinued_date": { "type": "string", "format": "date-time" } } }, "is_discontinued": { "type": "boolean", "description": "Whether the supplement has been discontinued" }, "associated_plan_id": { "type": "integer" }, "encounter_id": { "type": [ "integer", "null" ] }, "url_encounter": { "type": [ "string", "null" ], "description": "URL to the associated encounter" }, "created": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Bad Request - Invalid patient ID or supplement prescription ID" }, "500": { "description": "Server Error" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" \\\n --data '{\"discontinued_note\":\"No longer needed\",\"discontinued_date\":\"2024-01-15 14:30:00\"}' \\\n -X PATCH https://subdomain.md-hq.com/api/v1/patients/123/supplements/789/discontinue\n" } ] } }, "/users": { "get": { "operationId": "listUsers", "tags": [ "Users" ], "summary": "Get all users", "description": "Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC,\nso you’ll want to adjust for your local timezone. These endpoints allow you to query the system about\nusers (providers and other staff) in Cerbo.\n", "parameters": [ { "name": "limit", "in": "query", "description": "Defaults to 10, but can be overridden (max is 100)", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "If the returned data indicates that there is more than the limit\nresponses `(has_more: true)`, then it will offset the list to allow \nyou to cycle through users.\n", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "If a non-empty value is passed the system will include \ndeleted/suspended users in the return. If the argument is omitted only \nactive users will be returned.\n", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com /api/v1/users?limit=10\n" } ] } }, "/users/{id}": { "get": { "operationId": "showUser", "tags": [ "Users" ], "summary": "Get a single user's details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/users/11\n" } ] } }, "/users/validate_credentials": { "post": { "operationId": "validateUserCredentials", "tags": [ "Users" ], "summary": "Validate user credentials", "description": "This endpoint is rate limited to 3 attempts per 10 seconds, and 120 per 12-hour period.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "username" }, "password": { "type": "string" } }, "required": [ "user", "password" ] } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"user\":\"nickriviera\",\"password\":\"HiEverybody!\"}' -X POST\nhttps://subdomain.md-hq.com /api/v1/users/validate_credentials\n" } ] } }, "/patients/{patient_id}/tags": { "get": { "operationId": "listPatientTags", "tags": [ "Patient Tags" ], "summary": "Get all tags for a patient", "description": "Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for\nyour local timezone.\n", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "examples": [ "list" ] }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "tag_category": { "type": "string" }, "notes": { "type": "string" }, "date_applied": { "type": "string" } } } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/tags\n" } ] }, "post": { "operationId": "updatePatientTags", "tags": [ "Patient Tags" ], "summary": "Add or edit tags for a patient", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "notes": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X POST https://subdomain.md-hq.com/api/v1/patients/1/tags --data '{\"tags\":[{\"name\":\"New Patient\",\"notes\":\"Editing the note on this existing tag\"},{\"name\":\"Pediatric\",\"notes\":\"Adding this tag for the first time\"}]}'\n" } ] } }, "/patients/{patient_id}/tags/{tag_name}": { "delete": { "operationId": "deletePatientTag", "tags": [ "Patient Tags" ], "summary": "Delete patient tag", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } }, { "name": "tag_name", "in": "path", "schema": { "type": "string", "format": "urlencoded" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X DELETE https://subdomain.md-hq.com/api/v1/patients/1/tags/New%20Patient\n" } ] } }, "/patients/{patient_id}/vaccines": { "get": { "operationId": "listPatientVaccines", "tags": [ "Patient Vaccines" ], "summary": "Get all vaccine records for a patient", "description": "Please note: All dates listed (creation times, sign dates, date of service, update-times) are listed in UTC, so you'll \nwant to adjust for your local timezone. If you want to manage underlying supplement definitions please use the /v1/\nsupplements endpoints.\n", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "pt_vaccine" ] }, "id": { "type": "integer" }, "pt_id": { "type": "integer" }, "vaccine_id": { "type": "integer" }, "vaccine_name": { "type": "string" }, "dose": { "type": "integer" }, "site": { "type": "string" }, "notes": { "type": "string" }, "in_office": { "type": "boolean" }, "administeredby": { "type": "string" }, "administered": { "type": "string", "format": "datetime" }, "enteredby": { "type": "integer" }, "entered": { "type": "string", "format": "datetime" }, "next_due": { "type": "boolean" } } } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/vaccines\n" } ] } }, "/patients/{patient_id}/vitals/height": { "get": { "operationId": "listPatientHeightVitals", "tags": [ "Patient Vitals" ], "summary": "Get all height readings for a patient", "description": "Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for your local timezone.\n", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "height" ] }, "id": { "type": "integer" }, "pt_id": { "type": "integer" }, "date_taken": { "type": "string", "format": "date-time" }, "height": { "type": "integer" }, "units": { "type": "string" }, "comments": { "type": "string" }, "addedby": { "type": "integer" }, "created": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/vitals/height\n" } ] }, "post": { "operationId": "createPatientHeightVital", "tags": [ "Patient Vitals" ], "summary": "Add a height reading for a patient", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "height": { "type": "string", "description": "A string specifying the height reading" }, "units": { "type": "string", "description": "A string specifying the unit (inches or “cm”)" }, "comments": { "type": "string" }, "date_taken": { "type": "string", "description": "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": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } } } }, "/patients/{patient_id}/vitals/weight": { "get": { "operationId": "listPatientWeightVitals", "tags": [ "Patient Vitals" ], "summary": "Get all weight readings for a patient", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "weight" ] }, "id": { "type": "integer" }, "pt_id": { "type": "integer" }, "date_taken": { "type": "string", "format": "date-time" }, "weight": { "type": "integer" }, "units": { "type": "string" }, "comments": { "type": "string" }, "addedby": { "type": "integer" }, "created": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/vitals/weight\n" } ] }, "post": { "operationId": "createPatientWeightVital", "tags": [ "Patient Vitals" ], "summary": "Add a weight reading for a patient", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "weight": { "type": "string", "description": "A string specifying the weight reading" }, "units": { "type": "string", "description": "A string specifying the unit (“lbs” or “kg”)" }, "comments": { "type": "string" }, "date_taken": { "type": "string", "description": "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": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } } } }, "/patients/{patient_id}/vitals/bp": { "get": { "operationId": "listPatientBloodPressureVitals", "tags": [ "Patient Vitals" ], "summary": "Get all blood pressure readings for a patient", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "bp" ] }, "id": { "type": "integer" }, "pt_id": { "type": "integer" }, "date_taken": { "type": "string", "format": "date-time" }, "systolic": { "type": "integer" }, "diastolic": { "type": "integer" }, "pulse": { "type": "integer" }, "units": { "type": "string" }, "comments": { "type": "string" }, "addedby": { "type": "integer" }, "created": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/vitals/bp\n" } ] }, "post": { "operationId": "createPatientBloodPressureVital", "tags": [ "Patient Vitals" ], "summary": "Add a blood pressure reading for a patient", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "systolic": { "type": "string", "description": "A string specifying the systolic pressure reading" }, "diastolic": { "type": "string", "description": "A string specifying the diastolic pressure reading" }, "pulse": { "type": "string", "description": "A string specifying the pulse (b/min) reading" }, "comments": { "type": "string" }, "date_taken": { "type": "string", "description": "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": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } } } }, "/patients/{patient_id}/vitals/{vital_id}": { "get": { "operationId": "listPatientCustomVitals", "tags": [ "Patient Vitals" ], "summary": "Get all readings of a custom vital type for a patient", "parameters": [ { "name": "patient_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of patient" }, { "name": "vital_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "weight" ] }, "id": { "type": "integer" }, "pt_id": { "type": "integer" }, "vital_id": { "type": "integer" }, "date_taken": { "type": "string", "format": "date-time" }, "value": { "type": "string" }, "units": { "type": "string" }, "comments": { "type": "string" }, "abnormal": { "type": "boolean" }, "vital_url": { "type": "string", "examples": [ "https://{tenant}.md-hq.com/api/v1/vitals/330" ] }, "encounter_id": { "type": "integer" }, "url_encounter": { "type": "string" }, "order_id": { "type": "integer" }, "url_order": { "type": "string" }, "addedby": { "type": "integer" }, "created": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/vitals/weight\n" } ] }, "post": { "operationId": "createPatientCustomVital", "tags": [ "Patient Vitals" ], "summary": "Add a custom vital reading for a patient", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } }, { "name": "vital_id", "in": "path", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ], "description": "A string or boolean value for the vital reading, depending on the custom vital type." }, "abnormal": { "type": "boolean", "description": "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": { "type": "string" }, "date_taken": { "type": "string", "description": "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": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"value\":\"52\", \"abnormal\":true, \"comments\":\"This is an abnormally low glucose level\", \"date_taken\":\"2021-06-21 11:00:00 EST\"}' -X POST https://subdomain.md-hq.com/api/v1/patients/1/vitals/114 \n" } ] } }, "/patients/{patient_id}/questionnaires": { "get": { "operationId": "listPatientQuestionnaires", "tags": [ "Questionnaires" ], "summary": "Get All Questionnaires for a Patient", "description": "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. \n", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } }, { "name": "extended_details", "in": "query", "schema": { "type": "boolean" }, "description": "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.\n" } ], "responses": { "200": { "description": "- The `status` property tells you whether or not the questionnaire has been dismissed from the Patient Portal Queue\n- The `document_url` property (if not NULL) will return the API path for retrieving the human-readable questionnaire HTML file.\n" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET \"https://subdomain.md-hq.com/api/v1/patients/2/questionnaires?ßextended_details=true\"\n" } ] }, "post": { "operationId": "createPatientQuestionnaire", "tags": [ "Questionnaires" ], "summary": "Post a new Questionnaire", "description": "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. \n", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "questionnaire_type": { "type": "string" }, "questionnaire_name": { "type": "string" }, "html_content": { "type": "string", "format": "html", "description": "An HTML-formatted string that will serve as the human-readable version of the patient responses" }, "raw_data": { "type": "object", "properties": { "key": { "type": "string", "examples": [ "value" ] }, "key2": { "type": "string", "examples": [ "Some other value" ] }, "complex": { "type": "object", "properties": { "subkey": { "type": "string", "examples": [ "subval" ] }, "subkey2": { "type": "string", "examples": [ "subvalue2" ] } } } }, "description": "An object with key-value pairs that will represent the structured data underlying the patient responses. This allows us to analyze their response-data." } }, "required": [ "html_content", "raw_data" ] } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET \"https://subdomain.md-hq.com/api/v1/patients/2/questionnaires?ßextended_details=true\"\n" } ] } }, "/patients/{patient_id}/questionnaires/{questionnaire_id}": { "get": { "operationId": "showPatientQuestionnaire", "tags": [ "Questionnaires" ], "summary": "Get a Single Questionnaire’s Details", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } }, { "name": "questionnaire_id", "in": "path", "schema": { "type": "integer" } }, { "name": "extended_details", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/questionnaires/25?extended_details=true\n" } ] } }, "/patients/{patient_id}/portal/secure_messages": { "get": { "operationId": "listSecureMessages", "tags": [ "Secure Messages" ], "summary": "Get all secure messages for a patient", "description": "Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for\nyour local timezone.\n", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } }, { "name": "sent_by", "in": "query", "description": "Either “pt” (to get all messages sent by the patient) or “dr” (to get all messages sent to the patient from doctor/clinic)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/1/portal/secure_messages?sent_by=pt\n" } ] }, "post": { "operationId": "createSecureMessage", "tags": [ "Secure Messages" ], "summary": "Post a new secure message via the portal queue (patient → provider)", "parameters": [ { "name": "patient_id", "in": "path", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "between 1 and 54 characters long" }, "note": { "type": "string", "description": "at least 10 characters long" }, "dr_id": { "type": "integer", "description": "A valid ID of a non-archived, non-resource user who should respond to the message" }, "reply": { "type": "string", "enum": [ "secure message", "phone", "other", "none" ], "description": "how the patient would like to receive a response" } }, "required": [ "subject", "note" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean" }, "message": { "type": "string" }, "portal_queue_id": { "type": "integer" } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"subject\": \"Hello!\",\"note\":\"Have a great weekend\",\"reply\": \"none\"}' -X POST https://subdomain.md-hq.com/api/v1/patients/1/portal/secure_messages\n" } ] } }, "/supplements": { "get": { "operationId": "listSupplements", "tags": [ "Supplements" ], "summary": "Get all supplements", "description": "Please note: All dates listed are listed in UTC, so you’ll want to adjust for your local timezone. Also, the\nAPI responses include some routes that may not be available for your instance. Supplements can also be\naccessed through the /alternate_plans/ endpoints, but because most clinics handle supplements\nseparately you will want to use the /supplements/ endpoints unless you’re actively managing other\nproducts. 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.\n\nAlso note that while you have full usage rights over any supplement that was created/defined by your\npractice, and data sets that were installed or provided by a third party are subject to usage restrictions\n", "parameters": [ { "name": "limit", "in": "query", "description": "Defaults to 100, but can be overridden (max is 100)", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "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\n", "schema": { "type": "integer" } }, { "name": "active_only", "in": "query", "description": "If this parameter is set it will only include ACTIVE supplements", "schema": { "type": "boolean" } }, { "name": "vendor_code", "in": "query", "description": "If this parameter is set it will only supplements with matching vendor code (note, this is different from the external_ref_id).", "schema": { "type": "string" } }, { "name": "class", "in": "query", "description": "If this parameter is set it will only supplements with that class specified", "schema": { "type": "string" } }, { "name": "external_ref_id", "in": "query", "description": "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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/supplements?limit=10&class=sampleClass\n" } ] }, "post": { "operationId": "createSupplement", "tags": [ "Supplements" ], "summary": "Create a new supplement", "requestBody": { "required": true, "description": "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)", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "nicknames": { "type": "string" }, "vendor_code": { "type": "string" }, "description": { "type": "string" }, "external_ref_id": { "type": "string" }, "inactive": { "type": "boolean" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/supplements/2\n" } ] } }, "/supplements/search/{terms}": { "get": { "operationId": "searchSupplements", "tags": [ "Supplements" ], "summary": "Search all supplements", "parameters": [ { "name": "terms", "in": "path", "description": "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.\n", "schema": { "type": "string", "format": "urlencoded" } }, { "name": "limit", "in": "query", "description": "Defaults to 100, but can be overridden (max is 100)", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "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\n", "schema": { "type": "integer" } }, { "name": "active_only", "in": "query", "description": "If this parameter is set it will only include ACTIVE supplements", "schema": { "type": "boolean" } }, { "name": "vendor_code", "in": "query", "description": "If this parameter is set it will only supplements with matching vendor code (note, this is different from the external_ref_id).", "schema": { "type": "string" } }, { "name": "class", "in": "query", "description": "If this parameter is set it will only supplements with that class specified", "schema": { "type": "string" } }, { "name": "external_ref_id", "in": "query", "description": "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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/supplements/search/vitam%20d?limit=10&class=sampleClass\n" } ] } }, "/supplements/{supplement_id}": { "get": { "operationId": "showSupplement", "tags": [ "Supplements" ], "summary": "Get a single supplement", "parameters": [ { "name": "supplement_id", "in": "path", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/supplements/2\n" } ] }, "patch": { "operationId": "updateSupplement", "tags": [ "Supplements" ], "summary": "Update a supplement", "parameters": [ { "name": "supplement_id", "in": "path", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "description": "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.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "nicknames": { "type": "string" }, "vendor_code": { "type": "string" }, "description": { "type": "string" }, "external_ref_id": { "type": "string" }, "inactive": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data ' {\"name\":\"Updated Name\",\"vendor_code\":\"NewCode\"}' -X PATCH https://subdomain.md-hq.com/api/v1/supplements/12\n" } ] } }, "/tags": { "get": { "operationId": "listTags", "tags": [ "Tags" ], "summary": "Get All Tag Definitions from the Master Tag List", "description": "Please note: All dates listed (creation times, update-times) are listed in UTC, so you’ll want to adjust for\nyour local timezone. Please also note that this set of endpoints is for managing the master tag list - if\nyou’re looking to see how to grab patients with specific tags or how to apply tags to patients, please see\nthe /patients endpoints.\n", "parameters": [ { "name": "include_deleted", "in": "query", "schema": { "type": "boolean" }, "description": "Defaults to false, but any non-empty value will include deleted tags in the returned array" } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET \"https://subdomain.md-hq.com/api/v1/tags\"\n" } ] }, "post": { "operationId": "createTag", "tags": [ "Tags" ], "summary": "Create a new tag", "description": "Create a tag in the EMR. A created tag can be applied to a patient via the _Patient Tags_ endpoint.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the tag. The name must be unique." }, "category": { "type": "string", "description": "Category for the tag." }, "description": { "type": "string", "description": "Description for the tag." }, "displays_on_dash": { "type": [ "boolean", "null" ], "description": "Display the tag under the associated patient photo block when the patient chart or encounter note is opened." }, "note_displays_on_dashboard": { "type": [ "boolean", "null" ], "description": "Display the full text of any associated tag note in addition to showing the existence of the tag on the dashboard.\nThis behavior is dependent on `displays_on_dash` being `true` as well.\n" }, "displays_on_calendar": { "type": [ "boolean", "null" ], "description": "Display in the scheduler interface when scheduling an appointment for a tagged patient." }, "color": { "type": [ "string", "null" ], "description": "A valid six-digit hex code that defines the color for the tag." } }, "required": [ "name", "category", "description", "displays_on_dash", "note_displays_on_dashboard", "displays_on_calendar", "color" ] } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" }, "500": { "description": "Error\nReference the `error.message` value for more details.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "validation_error", "output_error", "unspecified_error" ] }, "message": { "type": "string" } } } } } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl --request POST \\\n --url https://subdomain.md-hq.com/api/v1/tags \\\n --header 'Authorization: Basic CREDS' \\\n --header 'content-type: application/json' \\\n --data '{\n \"name\": \"my tag\",\n \"category\": \"my category\",\n \"description\": \"my description\",\n \"displays_on_dash\": true,\n \"note_displays_on_dashboard\": true,\n \"displays_on_calendar\": true,\n \"color\": \"00ab3e\"\n}'\n" } ] } }, "/tags/{tag_id}": { "patch": { "operationId": "updateTag", "tags": [ "Tags" ], "summary": "Update a tag", "description": "Update a tag in the EMR. A tag can be applied to a patient via the _Patient Tags_ endpoint.\n", "parameters": [ { "name": "tag_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of tag to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the tag. The name must be unique." }, "category": { "type": "string", "description": "Category for the tag." }, "description": { "type": "string", "description": "Description for the tag." }, "displays_on_dash": { "type": [ "boolean", "null" ], "description": "Display the tag under the associated patient photo block when the patient chart or encounter note is opened." }, "note_displays_on_dashboard": { "type": [ "boolean", "null" ], "description": "Display the full text of any associated tag note in addition to showing the existence of the tag on the dashboard.\nThis behavior is dependent on `displays_on_dash` being `true` as well.\n" }, "displays_on_calendar": { "type": [ "boolean", "null" ], "description": "Display in the scheduler interface when scheduling an appointment for a tagged patient." }, "color": { "type": [ "string", "null" ], "description": "A valid six-digit hex code that defines the color for the tag." } }, "required": [ "name", "category", "description", "displays_on_dash", "note_displays_on_dashboard", "displays_on_calendar", "color" ] } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" }, "500": { "description": "Error\nReference the `error.message` value for more details.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_error", "not_found_error", "validation_error" ] }, "message": { "type": "string" } } } } } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl --request PATCH \\\n --url https://subdomain.md-hq.com/api/v1/tags/1 \\\n --header 'Authorization: Basic CREDS' \\\n --header 'content-type: application/json' \\\n --data '{\n \"name\": \"my tag\",\n \"category\": \"my category\",\n \"description\": \"my description\",\n \"displays_on_dash\": true,\n \"note_displays_on_dashboard\": true,\n \"displays_on_calendar\": true,\n \"color\": \"00ab3e\"\n}'\n" } ] }, "delete": { "operationId": "deleteTag", "tags": [ "Tags" ], "summary": "Destroy a tag", "description": "Destroy a tag in the EMR.\n", "parameters": [ { "name": "tag_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of tag to delete" } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" }, "500": { "description": "Error\nReference the `error.message` value for more details.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_error", "not_found_error", "validation_error" ] }, "message": { "type": "string" } } } } } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl --request DELETE \\\n --url https://subdomain.md-hq.com/api/v1/tags/1 \\\n --header 'Authorization: Basic CREDS'\n" } ] } }, "/tasks": { "get": { "operationId": "listTasks", "tags": [ "Tasks" ], "summary": "Get all tasks", "description": "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.\n", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "Defaults to 100, but can be overridden (max is 100)" }, { "name": "offset", "in": "query", "schema": { "type": "integer" }, "description": "If the returned data indicates that there is more than the limit\nresponses (has_more: true), then it will offset the list to allow you to cycle through a\nlong task list\n" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "search-filters": { "type": "object" }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "task" ] }, "id": { "type": "integer" }, "dr_id": { "type": "integer" }, "subject": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "datetime" }, "due_date": { "type": [ "string", "null" ], "format": "datetime" }, "reminder_time": { "type": [ "string", "null" ], "format": "datetime" }, "notes": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "normal", "high" ] }, "addedby": { "type": "integer" }, "patient_details": { "type": [ "object", "null" ], "properties": { "object": { "type": "string", "enum": [ "patient" ] }, "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "dob": { "type": "string", "format": "datetime" }, "sex": { "type": "string", "enum": [ "M", "F" ] }, "email1": { "type": "string" }, "url_patient_details": { "type": "string" } } }, "completed_on": { "type": [ "string", "null" ], "format": "datetime" }, "associated_resource_type": { "type": "string" }, "associated_resource_id": { "type": "integer" }, "created": { "type": "string", "format": "datetime" } } } } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/tasks\n" } ] }, "post": { "operationId": "createTask", "tags": [ "Tasks" ], "summary": "Post a new task", "description": "Please note: All dates listed (creation times, due dates, reminder dates) are listed in UTC, so you’ll want to adjust \nfor your local timezone.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dr_id": { "type": "integer", "description": "A valid ID of a non-archived, non-resource user who the task is being added for." }, "subject": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "normal", "high" ] }, "notes": { "type": "string" }, "pt_id": { "type": "integer", "description": "A valid ID of a non-archived patient to associate with the task." }, "due_date": { "type": "string", "format": "date-time", "description": "A time stamp (YYYY-MM-DD HH:MM:SS format) representing the due date for this task." }, "remind_minutes_before": { "type": "integer", "description": "Represents the number of minutes before your due date to \nremind the user of the task (due_date must be set).\n" } }, "required": [ "dr_id", "subject", "priority" ] } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" --data '{\"subject\": \"Follow up with John Doe\", \"notes\":\"He called with questions about his supplement plan\", \n\"dr_id\":\"1\", \"priority\":\"normal\", \"pt_id\":\"1\", \"due_date\":\"2019-12-1 11:15:00\", \"remind_minutes_before\":\"3600\"}' -X \nPOST https://subdomain.md-hq.com/api/v1/tasks\n" } ] } }, "/tasks/{task_id}": { "get": { "operationId": "showTask", "tags": [ "Tasks" ], "summary": "Get a single task", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the task" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "task" ] }, "id": { "type": "integer" }, "dr_id": { "type": "integer" }, "subject": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "datetime" }, "due_date": { "type": [ "string", "null" ], "format": "datetime" }, "reminder_time": { "type": [ "string", "null" ], "format": "datetime" }, "notes": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "normal", "high" ] }, "addedby": { "type": "integer" }, "patient_details": { "type": [ "object", "null" ], "properties": { "object": { "type": "string", "enum": [ "patient" ] }, "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "dob": { "type": "string", "format": "datetime" }, "sex": { "type": "string", "enum": [ "M", "F" ] }, "email1": { "type": "string" }, "url_patient_details": { "type": "string" } } }, "completed_on": { "type": [ "string", "null" ], "format": "datetime" }, "associated_resource_type": { "type": "string" }, "associated_resource_id": { "type": "integer" }, "created": { "type": "string", "format": "datetime" } } } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/tasks/123\n" } ] }, "patch": { "tags": [ "Tasks" ], "summary": "Update an existing task", "description": "This is a partial update endpoint — only fields included in the request body are modified.\nAll fields are optional. Fields not included in the request will remain unchanged.\n\nPlease note: All dates listed (creation times, due dates, reminder dates) are listed in UTC,\nso you'll want to adjust for your local timezone.\n", "operationId": "updateTask", "parameters": [ { "name": "task_id", "in": "path", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dr_id": { "type": "integer", "description": "A valid ID of a non-archived, non-resource user who the task is being added for." }, "subject": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "normal", "high" ] }, "notes": { "type": "string" }, "pt_id": { "type": "integer", "description": "A valid ID of a non-archived patient to associate with the task." }, "due_date": { "type": "string", "format": "date-time", "description": "A time stamp (YYYY-MM-DD HH:MM:SS format) representing the due date for this task." }, "remind_minutes_before": { "type": "integer", "description": "Represents the number of minutes before your due date to\nremind the user of the task (due_date must be set).\n" }, "completed_on": { "type": [ "string", "null" ], "format": "date-time", "description": "Marks the task as complete or incomplete. Pass a valid timestamp\n(YYYY-MM-DD HH:MM:SS format) to mark complete. The date must be\ntoday or in the past — future dates are rejected. Pass null or\nfalse to reset the task to incomplete.\n" }, "associated_resource_type": { "type": [ "string", "null" ], "enum": [ "soap", "documents" ], "description": "Links the task to a resource type (encounter note or document).\nPass null or empty to unlink. If set, associated_resource_id must\nalso be provided. If a pt_id is set, the linked resource must belong\nto the same patient.\n" }, "associated_resource_id": { "type": "integer", "description": "The ID of the linked resource. Required when associated_resource_type is set." } } } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Task not found" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -H \"Content-Type: application/json\" \\\n --data '{\"completed_on\": \"2026-02-16 09:00:00\"}' \\\n -X PATCH https://subdomain.md-hq.com/api/v1/tasks/1\n" } ] } }, "/vitals": { "get": { "tags": [ "Vitals" ], "summary": "Get all Custom Vital definitions from the Master Vitals List", "operationId": "getVitals", "description": "Please note: All dates listed (creation times, date taken) are listed in UTC, so you’ll want to adjust for\nyour local timezone.\n", "parameters": [ { "name": "show_all", "in": "query", "description": "If set to “true”, returns the entire custom vitals list, otherwise only returns the items configured to appear on patient charts", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/vitals?limit=10&offset=0&show_all=true\n" } ] } }, "/vitals/{vital_id}": { "get": { "tags": [ "Vitals" ], "summary": "Get single Custom Vital definition from the Master Vitals List", "operationId": "getVital", "parameters": [ { "name": "vital_id", "in": "path", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "vital_definition" ] }, "id": { "type": "integer" }, "name": { "type": "string", "examples": [ "Glucose" ] }, "name_full": { "type": "string", "examples": [ "Blood Glucose" ] }, "nicknames": { "type": [ "string", "null" ] }, "units": { "type": "string", "examples": [ "mg/dL" ] }, "unit_type": { "type": "string", "examples": [ "Numeric" ] }, "notes": { "type": "string" }, "normal_low": { "type": "string" }, "normal_high": { "type": "string" }, "dashboard_active": { "type": "boolean" }, "addedby": { "type": "integer" }, "created": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Vital not found" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/vitals/114\n" } ] } }, "/vitals_tag_groups": { "get": { "operationId": "listVitalsTagGroups", "tags": [ "Vitals" ], "summary": "Get vitals tag groups", "description": "Returns a list of provider-defined vitals tag groups. Tag groups are custom groupings\nof vitals/lab fields that allow providers to view selected vitals longitudinally (over time).\n\nThese groups are created within the Cerbo EMR interface and can be accessed via this\nendpoint for external visualization or reporting.\n\nOnly global tag groups (applicable to all patients) are returned. Patient-specific\ntag groups are not included.\n", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "total_count": { "type": "integer", "description": "Number of tag groups returned" }, "has_more": { "type": "boolean", "example": false, "description": "Always false (no pagination)" }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the tag group", "example": "Thyroid Panel" }, "included_fields": { "type": "array", "description": "Array of vital/lab field names included in this group (uppercase)", "items": { "type": "string" }, "example": [ "TSH", "T3", "T4", "FREE T4" ] }, "created": { "type": "string", "format": "date-time", "description": "When the tag group was created (UTC)", "example": "2024-03-15T14:30:00Z" }, "created_by": { "type": "integer", "description": "User ID who created the tag group", "example": 42 } } } } } }, "example": { "object": "list", "total_count": 2, "has_more": false, "data": [ { "name": "Thyroid Panel", "included_fields": [ "TSH", "T3", "T4", "FREE T4", "FREE T3" ], "created": "2024-03-15T14:30:00Z", "created_by": 42 }, { "name": "Metabolic Panel", "included_fields": [ "GLUCOSE", "BUN", "CREATININE", "SODIUM", "POTASSIUM" ], "created": "2024-02-20T09:15:00Z", "created_by": 15 } ] } } } }, "400": { "description": "Bad Request" }, "500": { "description": "Internal Server Error" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/vitals/tag_groups\n" } ] } }, "/patients/{pt_id}/lab_results": { "get": { "tags": [ "Patient Lab Results" ], "summary": "Get all lab results for a patient", "operationId": "getPatientLabResults", "description": "Please note: All dates listed (creation times, date taken) are listed in UTC, so you'll want to adjust for\nyour local timezone.\n", "parameters": [ { "in": "path", "name": "pt_id", "schema": { "type": "integer" }, "description": "ID of patient" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "date": { "type": "string", "format": "datetime" }, "units": { "type": "string" }, "references_range": { "type": "string" }, "value": { "type": "string" }, "flag": { "type": "string" }, "ntes": { "type": "object", "additionalProperties": { "type": "object", "properties": { "set_id": { "type": "string" }, "source_of_comment": { "type": "string" }, "comment": { "type": "string" } } } }, "date_saved_to_chart": { "type": "string", "format": "datetime" }, "src_lab": { "type": "string" }, "obx3": { "type": "string" }, "manual_entry": { "type": "boolean" }, "manual_entry_id": { "type": [ "string", "null" ] } } } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Patient not found" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -H \"Authorization: Basic CREDS\" -X GET https://subdomain.md-hq.com/api/v1/patients/2/lab_results\n" } ] } } }, "components": { "securitySchemes": { "main_auth": { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "http://example.com/api/oauth/dialog", "scopes": { "read:users": "read users info", "write:users": "modify or remove users" } } } }, "api_key": { "type": "apiKey", "in": "header", "name": "api_key" }, "basic_auth": { "type": "http", "scheme": "basic" } } } }