Software Release Version

DrCloudEHR 2020, 2025

API Description

The DrCloud MU3 API is a web-based, USCDI-compliant API that is used to request and receive data from a DrCloudEHR server.

  • When a user 'logs in' to the API, a token is received that can be used to authenticate later API calls.
    • User creation is handled by the existing User management interface.
    • Tokens are valid for up to 60 minutes.   However, a user may request a new token at any time.
  • Parameters are passed to the API scripts using POST variables.
    • The programs written to test the API are PHP scripts that use libcurl to communicate with the API scripts.
  • The scripts return requested MU3 data formatted as an XML file.
    • For API calls that request MU3 section data, the returned files are generated by DrCloud's CCDA reporting code.

Basic Workflow

  • User 'logs in' to the API by running login.php.
    • A token is received that can be used to authenticate later API calls.
    • User creation is handled by the existing User management interface.
    • Tokens are valid for up to 60 minutes.   However, a user may request a new token at any time.
  • If the user does not know the patient's ID, it can be found by running either patientlist.php or patientsearch.php.
  • getpatdata.php can then be run to query the API for the patient's USCDI data.

Technical details

  • The DrCloudEHR server uses HTTPS to ensure a secure data connection.
  • Parameters are passed to the API scripts using POST variables.
    • Most of the API calls return their result as an XML file.
    • The script that handles MU3 data request returns a JSON file.

MU3 API

This table shows the API for Meaningful Use Stage 3 validation.   Most of the API calls make use of POST variables.   Browser-based HTML forms can be used to access these, though we have been able to use both PHP scripts, as well as Postman (https://getpostman.com) to test the API.


FilenamePOST Variables

Returns

(status = 0)

Errors

(status != 0)

Comments
login.php
  • username
  • password
  • site

An XML file containing an array of records, consisting of:

  • token
  • id (user's id)
  • provider
  • firstname
  • lastname
  • title
  • -1 : Username/Password incorrect.

Generates the API session token. Token is valid for 1 hour, but you can generate a new token at any time before then.


patientlist.php
  • site
  • token

XML file containing an array of records containing:

  • id
  • pid
  • firstname
  • lastname
  • middlename
  • phone
  • dob
  • gender
  • -1 : ERROR: Sorry, there was an error processing your data. Please correct and submit the information again.
  • -2 : You are not Authorized to perform this action
  • -3 - Invalid Token

Get a list of all patients.

Used to find patient ID's, if you don't know the patient's name.

patientsearch.php
  • token
  • firstname (optional)
  • lastname
  • site

An XML file containing:

  • id
  • pid
  • firstname
  • lastname
  • phone
  • dob
  • gender

  • -1 : Could not find results
  • -2 : You are not Authorized to perform this action
  • -3 : Invalid Token
  • -4 : Must specify firstname or lastname

Search for a patient by first name or last name.

You must specify a last name if you want to specify a first name.

example POST variables:

firstname = "Artemis", lastname="Osborne"

Returns a list of patient entries that match at least one of the search parameters.


getpatdata.php
  • site
  • pid
  • token
  • enable_date_filter (optional)
  • start_date (optional)
  • end_date (optional)
  • section_num (optional)

If enable_date_filter is not set, date filtering will be enabled. Note that the code simply checks for the existence of enable_date_filter. Set this to "1", so that it doesn't confuse people.

The date filter applies to the following sections:

#section
8Problems
9Medications
10Allergies
11Lab Tests
12Lab Test Results
13Vital Signs
15Procedures
17Immunizations
18Implantable Devices

If enable_data_filter is set and start_date is not set, the date 1970-01-01 will be used as the start date.

If enable_data_filter is set, and end_date is not set, the current date will be used as the end date. Note that this date is set by the server and not the client.


A JSON file containing data for the requested section.

Selecting any of the "demographics" sections (1-6) will return all of the demographics sections.

Selecting any of the other sections will also return the Demographics sections in addition to the selected section.

If section_num was set to zero, or no section_num was specified, all sections will be returned.


  • -1 : Error processing patient record
  • -2 : You are not authorized to perform this action
  • -3 : Invalid Token
  • -4 : Invalid section number. Must be between 0 and 21

If section 14 is selected:

  • -5 : Section 14 no longer exists


#These sections return -1 when no data is available .
8Problems
9Medications
10Allergies
11Lab Tests
12Lab Results
13Vital Signs
15Procedures
16Care Team Members
17Immunizations
18Implantable Devices
19Assessments/Treatment Plan
20Goals
21Health Concerns

Returns the USCDI sections for MU Stage 3.



Section numbers

#

section
1Patient name
2Sex
3Date of Birth
4Race
5Ethnicity
6Preferred language
7Smoking status
8Problems
9Medications
10Allergies
11Lab Tests
12Lab Test Results
13Vital Signs
15Procedures
16Care team members
17Immunizations
18Implantable device list
19Assessment and Treatment Plan
20Goals
21Health Concerns
get_ccda.php
  • site
  • pid
  • token
  • enable_date_filters (optional)
  • start_date (optional)
  • end_date (optional)


Returns the USCDI sections as a C-CDA file for the selected patient, with optional start/end date constraints.
  • -2 : You are not authorized to perform this action
  • -3 : Invalid Token


Testing with Postman

Postman (https://www.getpostman.com) can be used to test the API.   The DrCloud MU3 collection is available on request.

The "Login" request runs the "login.php" script, which must always be run before running any other Request, as documented above.

"Request CCDA" returns a Zip file containing the CCDA XML file, so instead of pressing the "Send" button, click on the little down arrow to the right, which will display the "Send and Download" button.   Clicking on that will allow you to download the file.

 


Terms of Use

This is a legal agreement ("Agreement") between you, the "User", and Ensoftek Inc ("Company").  BY ACCEPTING THIS AGREEMENT, YOU ARE CONSENTING TO BE BOUND BY ITS TERMS.Read the terms of the agreement here.

Definitions

As used herein: the "Software" means the DrCloudEHR Application Programming Interface (API).

License Grant

All Users SHALL possess an active DrCloudEHR license agreement.   Use of this Software SHALL BE COVERED BY THE TERMS OF THAT LICENSE AGREEMENT. If you do not have a license, existing customers can email support@drcloudemr.com. New Customers, please email info@drcloudehr.com

Limitation of Liability

Limitation of Liability for this Software SHALL BE COVERED BY THE TERMS OF THAT LICENSE AGREEMENT.

License Restrictions

The Company may limit the number of persons that can use the Software.

Mandatory Disclosures

Please refer to https://drcloudehr.com/promoting-interoperability-transparency-and-disclosure-requirements/

Usage

If you become aware of any unauthorized access or use of the Software, you shall immediately notify the Company.



  • No labels