PI EHR API Documentation
PI EHR Application Program Interface (API)
The PI EHR API provides electronic and secure access by 3rd party EHR systems to patient health information that is maintained by the PI EHR system. Please contact Professional Imaging, LLC at mike@proimagetx.com if you are seeking approval for API access or you have any questions regarding this API.
The PI EHR API interface is URL based. Following is the basic URL syntax used by 3rd party EHR systems to invoke the PI EHR API:
https://portal.proimagetx.com/PI_EHR_API?c=<command_string>
where the syntax for <command_string> is shown below. In all cases, uuuuuu is an authorized API user ID and pppppp is the password. The user ID and password will be provided once approval for access has been granted (as mentioned above).
Patient Lookup (ptLkup) command - uuuuuu^pppppp^ptLkup^firstname^lastname^DOB - where firstname, lastname and DOB are patient first name, patient last name and patient date of birth. This command returns kkkkkk, a patient key value required for the ptDocQry and ptInfoQry commands (below).
Patient Document Query (ptDocQry) command - uuuuuu^pppppp^ptDocQry^kkkkkk^ssssssss^eeeeeeee - This command downloads a zip file containing one or more CCDA files based on the ssssssss (start) & eeeeeeee (end) dates. When no dates are provided, only the most current, provider approved CCDA data is returned. For each CCDA file returned, a file with a name that matches the CCDA file (except that it ends with "_SHA2.txt") is also returned. The ...SHA2.txt file will contain a SHA256 hash digest for the corresponding CCDA file that can be used to verify the CCDA file contents. The kkkkkk parameter is a patient key value that was returned by the Patient Lookup command (above).
Patient Info Query (ptInfoQry) command - uuuuuu^pppppp^ptInfoQry^kkkkkk^xxxxxx^ssssssss^eeeeeeee - This command returns requested patient info as one or more partial CCDA ClinicalDocument XML segments (ClinicalDocumentSegment elements). The output is based on ssssssss (start) & eeeeeeee (end) dates and an xxxxxx parameter, which is a unique combination of CCDA xml node name(s) that identify the requested patient information (for example, {recordTarget}{patientRole}{patient}{raceCode} would be used to obtain race information - more examples are provided below). A ClinicalDocumentSegment element is returned for each CCDA file found in the patient's medical record that is between the specified start and end dates. If no start and end dates are provided, then only one ClinicalDocumentSegment element is returned from the most recent provider approved CCDA document file. The kkkkkk parameter is a patient key value that was returned by the Patient Lookup command (above).
The returned CCDA ClinicalDocumentSegment(s) are wrapped in a root xml node. After the ClinicalDocumentSegment(s), a sha2Digest element is included that contains one SHA256 hash digest for all of the ClinicalDocumentSegment elements. This digest can be used to verify the string starting from the first <ClinicalDocumentSegment> element and ending with the last </ClinicalDocumentSegment> element.
The returned ClinicalDocumentSegment(s) may contain information that is outside the selected date range. This is done to insure patient safety. For example, Medications could include medications that were completed prior to the start date. In this case, the API would return all medications in the patient's medications list (both current and completed medications) that are found in the source CCDA file (associated with the returned ClinicalDocumentSegment).
Also to insure patient safety, all ClinicalDocumentSegments returned by this command include the following xml elements. These elements include a <recordTarget> that identifies the specific patient and includes all patient demographic data (in place of the dddddd shown below). The other xml elements below (realmCode through versionNumber) identify the source CCDA file and its version and format.
<realmCode code="US" />
<typeId root="2.16.840.1.113883.1.3" extension="POCD_HD000040" />
<templateId root="2.16.840.1.113883.10.20.22.1.1" extension="2015-08-01" />
<templateId root="2.16.840.1.113883.10.20.22.1.1" />
<templateId root="2.16.840.1.113883.10.20.22.1.2" extension="2015-08-01" />
<templateId root="2.16.840.1.113883.10.20.22.1.2" />
<id root="2.16.840.1.113883.19.5.99999.1" extension="PIEMR3.20190524085945643" />
<code code="34133-9" codeSystem="2.16.840.1.113883.6.1" codeSystemName="LOINC" displayName="Summarization of Episode Note" />
<title>Summarization of Episode Note (DOS from 10/5/11 to 6/22/15)</title>
<effectiveTime value="20190524205945-0500" />
<confidentialityCode code="N" codeSystem="2.16.840.1.113883.5.25" />
<languageCode code="en-US" />
<setId root="2.16.840.1.113883.19.5.99999.19" extension="PIEMR3.20190524085945643" />
<versionNumber value="1" />
<recordTarget>dddddd</recordTarget>
When non-demographic data (Problems, Medications, Lab Tests, etc.) is requested, the returned ClinicalDocumentSegment(s) will contain the following <component> element, where ssssss is a <section> element that contains the requested data. This section element contains sub-elements that are specific to the type of data requested.
<component><structuredBody><component>ssssss </component></structuredBody></component>
Note that the format and content of the xml elements returned by this command are based on the CCDA document standards that were applicable for the source CCDA file. Also note that selecting Health Concerns will return both a CDA Health Concerns section as well as the CDA Problems List section. This is to identify problems that have matching health concerns (with matching <id ...> values). Also, selecting Assessment and Plan of Treatment will return both the CDA Plan of Treatment section as well as the CDA Assessment section.
Following are examples of values to use for the xxxxxx parameter (the CCDA xml node names that identify desired patient information). So for example, a value of {recordTarget}{patientRole}{patient}{birthTime} would be used for xxxxxx if want to retrieve Date of Birth information. WARNING - this parameter is case sensitive and > and < characters are not permitted. You must use the { and } characters instead.
Patient Name - {recordTarget}{patientRole}{patient}{name}
Sex - {recordTarget}{patientRole}{patient}{administrativeGenderCode}
Date of Birth - {recordTarget}{patientRole}{patient}{birthTime}
Race - {recordTarget}{patientRole}{patient}{raceCode}
Ethnicity - {recordTarget}{patientRole}{patient}{ethnicGroupCode}
Preferred Language - {recordTarget}{patientRole}{patient}{languageCommunication}
Care Team Members - {recordTarget}{patientRole}{patient}{documentationOf}
Smoking Status - {component}{structuredBody}{component}{section}{templateId root="2.16.840.1.113883.10.20.22.2.17"}
Problems - {component}{structuredBody}{component}{section}{templateId root="2.16.840.1.113883.10.20.22.2.5.1"}
Medications - {component}{structuredBody}{component}{section}{templateId root="2.16.840.1.113883.10.20.22.2.1.1"}
Medication Allergies - {component}{structuredBody}{component}{section}{templateId root="2.16.840.1.113883.10.20.22.2.6.1"}
Lab Tests - {component}{structuredBody}{component}{section}{templateId root="2.16.840.1.113883.10.20.22.2.3.1Abbr"}
Lab Values/Results - {component}{structuredBody}{component}{section}{templateId root="2.16.840.1.113883.10.20.22.2.3.1"}
Vital Signs - {component}{structuredBody}{component}{section}{templateId root="2.16.840.1.113883.10.20.22.2.4.1"}
Procedures - {component}{structuredBody}{component}{section}{templateId root="2.16.840.1.113883.10.20.22.2.7.1"}
Immunizations - {component}{structuredBody}{component}{section}{templateId root="2.16.840.1.113883.10.20.22.2.2.1"}
Unique Device Identifiers - {component}{structuredBody}{component}{section}{templateId root="2.16.840.1.113883.10.20.22.2.23"}
Plan of Care - {component}{structuredBody}{component}{section}{templateId root="2.16.840.1.113883.10.20.22.2.10"}
Assessment and Plan of Treatment - {component}{structuredBody}{component}{section}{templateId root="2.16.840.1.113883.10.20.22.2.10"}
Goals - {component}{structuredBody}{component}{section}{templateId root="2.16.840.1.113883.10.20.22.2.60"}
Health Concerns - {component}{structuredBody}{component}{section}{templateId root="2.16.840.1.113883.10.20.22.2.58"}
Functional Status - {component}{structuredBody}{component}{section}{templateId root="2.16.840.1.113883.10.20.22.2.14"}
Parameter Types and Exception Logic - All parameters have a type of string. Exceptions for the ptLkup and ptInfoQry commands are handled by returning a text error message (type string) the starts with "Error -". If a string is returned that does not start with "Error -", then the ptLkup or ptInfoQry command has completed successfully. Exceptions for the ptDocQry command are returned as error message(s) contained in a download file with a file name in the following format; ERROR - yyyy-MM-dd HH.mm.ss.txt. If the returned download file is a zip file (file name ending in ".zip"), then the ptDocQry command was successful.
Software Requirements - An application development environment is required that permits use of commands capable of sending a URL to a website and receiving a response as a text string (for the ptLkup and ptInfoQry commands) and as a download file (for the ptDocQry command). Visual Studio .Net applications are an ideal way to do this. Once you have been granted access to the PI EHR API, we can provide c# sample code that demonstrates use of the API.
Terms of Use - The PI EHR API is considered a publicly available interface and is provided on "as is" basis. Professional Imaging, LLC provides no warranty as to the suitability of this API for any 3rd party application. Use of this API, constitutes agreement that the API user will hold Professional Imaging, LLC and any associated parties harmless for any damages arising from the use of this API. While the API is designed with a secure SSL network interface, the API user is solely responsible for insuring that patient information security is maintained including adherence to HIPAA and other applicable patient privacy regulations.