Sevocity EHR API Version 1.1
This documentation provides access information for searching and fetching patient data from the Common Clinical Data Set utilizing Sevocity EHR API’s. The intended purpose satisfies the requirements of 2015 CEHRT Regulations § 170.315(g)(7), § 170.315(g)(8), and §170.315(g)(9).
Terms and Conditions of Use
CONCEPTUAL MINDWORKS, INC.
SEVOCITY® EHR API
TERMS AND CONDITIONS of USE agreement
The terms set forth below are the Terms and Conditions of Use between you and the entity on whose behalf you will be using the API, (collectively, “you” or “Developer”), and Conceptual MindWorks, Inc., a Texas corporation (“CMI”) d/b/a Sevocity, the owner of SEVOCITY® EHR and SEVOCITY® EHR API (collectively, “SEVOCITY®”) and constitute a legal and binding agreement. By accessing SEVOCITY®, you agree that you, and the business on whose behalf you are acting, agree to all of the terms and conditions set forth below (this “Agreement”).
1. CMI LICENSE.
CMI hereby grants you a non-exclusive, non-transferable, limited, revocable license to access SEVOCITY® for the purposes described herein, under the terms and conditions set forth in this Agreement.
2. YOUR DUTIES.
(a) You shall use SEVOCITY® only to assist in the development of software applications (“Applications” or “API”) that will access Protected Health Information (“PHI”) of patients with health information in SEVOCITY®.
(b) You agree to comply with the SEVOCITY® EHR API Access instructions. You understand that CMI may limit your use of the API.
(c) You shall not distribute, sell, lease, license, or transmit SEVOCITY® to any third party or use SEVOCITY® on behalf of any third party. You shall not sublicense, copy, record, reproduce, reverse engineer, publish, translate or transfer possession, reverse compile or disassemble or prepare derivative works from SEVOCITY®.
(d) You shall not introduce or permit to be introduced into SEVOCITY® any virus, worm, Trojan horse or other software routine program or mechanism to permit unauthorized access into, to disable, to erase in whole or in part or otherwise to adversely affect SEVOCITY®.
Violation or default by you of any requirements or restrictions set forth in this Section 2 shall constitute breach of a material provision of this Agreement. You understand that CMI may restrict or condition access and use at any time if it reasonably believes that such continued access or use will imminently and materially disrupt, degrade or injure continued function or use of SEVOCITY®.
3. WARRANTIES.
You warrant to CMI that you:
(a) are authorized by the entity on whose behalf you will be using the API to bind them to this Agreement;
(b) are not barred from using or receiving APIs under the applicable laws of the United States;
(c) are authorized to access any PHI that you request through SEVOCITY®;
(d) will use SEVOCITY® and all information obtained from SEVOCITY® in accordance with all applicable laws, and in particular, with applicable federal and state security and privacy laws and regulations; and
(e) will not share with anyone else these terms and conditions, CMI’s API Access instructions or SEVOCITY®
4. SECURITY, CONFIDENTIALITY, AND PROPRIETARY INFORMATION.
(a) Security. You shall take reasonable steps to maintain the security of SEVOCITY® and information in SEVOCITY®’s possession. You acknowledge that no security measures are perfect and that security breaches may occur despite commercially reasonable efforts. You shall promptly report to CMI any material system, equipment, or software malfunction, error, breakage or breach that involves the security of SEVOCITY® or data in SEVOCITY® that you detect or that you believe is imminent or is likely to have occurred. You shall reasonably cooperate with CMI in efforts to reduce the effects of any such malfunction, error, breakage or breach, to mitigate damage and restore lost code or data.
(b) Confidentiality. You shall comply fully with all applicable provisions of any privacy and/or security regulations promulgated pursuant to HIPAA, HITECH or any other federal or state applicable law.
(c) Proprietary Information. SEVOCITY®, all related intellectual property, and the activities and functions performed by CMI shall be and remain the exclusive property of CMI. All derivative works prepared from SEVOCITY® and all analysis of non-protected health information shall be and remain the exclusive property of CMI.
5. DISCLAIMERS.
(a) EXCEPT AS EXPRESSLY PROVIDED HEREIN, CMI DOES NOT MAKE NOR SHALL IT BE DEEMED TO HAVE MADE ANY REPRESENTATIONS OR WARRANTIES OF ANY KIND OR NATURE, DIRECTLY OR INDIRECTLY, WHETHER EXPRESS OR IMPLIED WITH RESPECT TO SEVOCITY®; AND CMI EXPRESSLY DISCLAIMS ALL WARRANTIES OF MERCHANTABILITY, DESIGN, OPERATION, FITNESS FOR A PARTICULAR PURPOSE, NONINTERFERENCE WITH INFORMATION, AND ACCURACY OF INFORMATIONAL CONTENT AND ALL WARRANTIES ARISING FROM CONDUCT, COURSE OF DEALING OR CUSTOM OR USAGE IN TRADE.
(b) You acknowledge and agree that SEVOCITY® involves complex computer hardware and software that is not necessarily free from defects or able to operate without interruption and that CMI does not warrant the same. CMI does not warrant that SEVOCITY® is free from errors or defects and shall not be responsible with respect to any liabilities arising therefrom; and, SEVOCITY® and each part or aspect of it is provided “AS IS.” CMI makes no warranty and shall not be responsible with respect to the results that may be obtained from the use of SEVOCITY® or the accuracy, reliability, or functionality of any data or other information retrieved by you in connection with SEVOCITY®.
(c) Under no circumstances shall CMI be responsible for the acts or omissions of third party sources. CMI is not responsible for the accuracy, reliability, or functionality of any third party information, CMI makes no warranty concerning the same, and, all third party information is provided on an “AS IS” basis only.
(d) CMI makes no warranty and shall not be responsible with respect to any interception, access, loss, impairment, delay, corruption, or damage of any outbound code or data after the packet leaves the back end of CMI’s Internet server or of any inbound code or data before the packet enters the back end of CMI’s Internet server
6. INDEMNIFICATION.
You and the business for whom you act agree to indemnify and hold harmless CMI and CMI’s officers, directors, agents, employees and
contractors from and against any and all claims, damages, and costs (including reasonable attorneys’ fees) resulting from or arising out of
your use of SEVOCITY®, your negligence, your tortious act, or your breach of the warranties in Section 3.
7. LIABILITY LIMITATION.
NOTWITHSTANDING ANYTHING TO THE CONTRARY IN THE AGREEMENT, CMI SHALL NOT BE LIABLE FOR ANY DIRECT,
INDIRECT, EXEMPLARY, PUNITIVE, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES WHATSOEVER, OR ANY DAMAGES
FOR LOSS OF PROFITS, REVENUE, DATA OR USE, INCURRED BY YOU OR ANY THIRD PARTY, WHETHER IN AN ACTION IN
CONTRACT OR TORT.
8. GENERAL TERMS.
(a) Entire Agreement; Assignment. This Agreement constitutes the entire agreement between the parties. You may not assign this Agreement without the prior written consent of CMI. CMI may assign this Agreement at any time.
(b) Force Majeure. No failure, delay or default in performance of any obligation under this Agreement shall constitute an event of default or a breach of representation or warranty under this Agreement if and to the extent it is caused by a strike; fire; legal act of a public authority; unavoidable casualty; civil disorder; vandalism; war; act of terrorism; inclement weather; failure of the Internet; failure or error of any Internet access provider; failure or impairment of any lines of transmission belonging to any third party; failure or impairment of any third party server, router, other equipment or software through which Internet transmissions occur; or, other extraordinary cause if such cause or condition is beyond the reasonable control of the party otherwise chargeable, for so long as such cause or condition continues and for a reasonable period of time thereafter.
(c) Governing Law. The laws of the State of Texas, excluding its conflicts laws, shall govern this Agreement and the entire relationship between the parties hereto, and all matters arising out of or relating to this Agreement. Venue shall be in Bexar County, Texas. The U.N. Convention for the International Sale of Goods shall not apply to this Agreement.
(d) Arbitration. In the event of a dispute that you and CMI have been unable to resolve in a timely manner through good faith negotiations, such dispute shall be resolved by binding arbitration according to the rules of the American Arbitration Association. Notwithstanding the foregoing, either party may seek injunctive relief in court to prevent imminent harm, on condition that such party shall immediately submit the controversy to arbitration pursuant to this Section.
(e) Severability. If any portion of this Agreement is held to be invalid, unenforceable or in violation of any law, such provision shall not affect or impair the validity and enforceability of the remainder of this Agreement, and the arbitrator or court making such determination shall have the power to alter or amend such provision so that it shall be enforceable consistent with the intention of the parties.
(f) Notice. You must give any notices to CMI via certified mail or overnight delivery at Conceptual MindWorks, Inc., 13409 NW Military, Ste. 201, San Antonio, Texas 78231. CMI may give notices to you through this website or another method.
Introduction
This guide is written for third party developers or patients who are developing software applications that will access the Protected Health Information (PHI) of patients on Sevocity.
Pre-Requisites
Patients who wish to utilize a third party developer’s application to access PHI via the Sevocity EHR API must be a patient of a healthcare organization that utilizes Sevocity EHR and be registered in the Sevocity EHR portal. This registration is provided at the patient’s clinic.
Patients wishing to utilize a third party developer’s application to access PHI via the Sevocity EHR API must have a secret token provided by the clinic – this secret token is scanned into the Google Authenticator which is available on the Android and iOS smartphones.
Server Access
The Sevocity EHR API server can be accessed via:
https://www.medicalofficeconnect.com:9003/thirdpartyapi/ThirdPartyController
Workflow
The workflow for using the API is shown in the following diagram:
API Documentation
The following pages demonstrate the use of Sevocity EHR API including request and response examples and XML schema for requests and
responses. For responses that include encoded data, the data is BASE64 encoded. For compressed data, the compression algorithm is ZLIB.
1. Register User
2. Login
3. Request CCDA
4. Get List of CCDAs
5. Get CCDA
6. Logout
Register User
Purpose and Use: Register a user and match the user with the providers provided. This will return a session id that can be used for the duration of the session. It is assumed that the patient using the API via a third party is already a user of the patient portal but wishes to use the 3rd party applications. The code is the 6 digit number generated by Google Authenticator on the user’s smartphone. The apikey must be in the http header with key apikey.
Register User : Request Schema
<xs:schema attributeFormDefault="unqualified"
elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="request">
<xs:complexType>
<xs:sequence>
<xs:element type="xs:string" name="username" use="required"/>
<xs:element type="xs:string" name="action"
use="required"fixed="registeruser"/>
<xs:element type="xs:string" name="password" use="required"/>
<xs:element type="xs:string" name="firstname" use="required"/>
<xs:element type="xs:string" name="lastname" use="required"/>
<xs:element type="xs:string" name="zipcode" use="required"/>
<xs:element type="xs:date" name="dob" use="required"/>
<xs:element type="xs:string" name="portalusername" use="required"/>
<xs:element type="xs:string" name="code" use="required"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Register User : Request Example
<request> <username>dan</username> <action>registeruser</action> <password>password</password> <firstname>Daniel</firstname> <lastname>Jones</lastname> <zipcode>78230</zipcode> <dob>1949-01-01</dob> <portalusername>dan1</portalusername> <code>242343</code> </request>
Register User : Reply Schema
For success: <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="reply"> <xs:complexType> <xs:sequence> <xs:element type="xs:string" name="code" use="required" fixed="OK"/> <xs:element type="xs:string" name="sessionid" use="required"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema> For failure: <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="reply"> <xs:complexType> <xs:sequence> <xs:element type="xs:string" name="code" fixed="FAIL"/> <xs:element type="xs:string" name="message"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
Register User : Reply Example
For success: <reply> <code>OK</code> <sessionid>234234234_23r4klsajf_kasfkj</sessionid> </reply> For failure: <reply> <code>FAIL</code> <message>Patient cannot be uniquely identified.</message> </reply>
Login
Purpose and Use: Verify the username/password and two factor code. The session id can be used for the other features, e.g. request CCDA, etc. The code is the 6 digit number generated by Google Authenticator on the user’s smartphone. The apikey must be in the http header with key apikey.
Login : Request Schema
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="request"> <xs:complexType> <xs:sequence> <xs:element type="xs:string" name="username" use="required"/> <xs:element type="xs:string" name="action" use="required" fixed="login"/> <xs:element type="xs:string" name="password" use="required"/> <xs:element type="xs:int" name="code" use="required"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
Login : Request Example
<request> <username>dan</username> <action>login</action> <password>password</password> <code>123456</code> </request>
Login : Reply Schema
For success: <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="reply"> <xs:complexType> <xs:sequence> <xs:element type="xs:string" name="code" use="required" fixed="OK"/> <xs:element type="xs:string" name="sessionid" use="required"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema> For failure: <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="reply"> <xs:complexType> <xs:sequence> <xs:element type="xs:string" name="code" use="required" fixed="FAIL"/> <xs:element type="xs:string" name="message" use="required"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
Login : Reply Example
For success: <reply> <code>OK</code> <sessionid>2347234_78234kcasdf_8234234</sessionid> </reply> For failure: <reply> <code>FAIL</code> <message>Username/Password do not match.</message> </reply> <reply> <code>FAIL</code> <message>Code does not match.</message> </reply>
Request CCDA
Purpose and Use: Request a ccda. The resulting ccda will be stored for future retrieval via other calls. The session id being passed in must in the http header with key sessionid. If the startdate and enddate are not present, the last encounter is selected for the CCDA. The apikey must be in the http header with key apikey.
Request CCDA: Request Schema
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="request"> <xs:complexType> <xs:sequence> <xs:element type="xs:string" name="username" use="required"/> <xs:element type="xs:string" name="action" use="required" fixed="requestCCDA"/> <xs:element type="xs:date" name="startdate"/> <xs:element type="xs:date" name="enddate"/> <xs:element name="category" use="required" minOccurs="1"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="all"/> <xs:enumeration value="allergies"/> <xs:enumeration value="medications"/> <xs:enumeration value="problems"/> <xs:enumeration value="procedures"/> <xs:enumeration value="labs"/> <xs:enumeration value="encounters"/> <xs:enumeration value="functional_status"/> <xs:enumeration value="immunizations"/> <xs:enumeration value="plan"/> <xs:enumeration value="social_history"/> <xs:enumeration value="vitals"/> <xs:enumeration value="mental_status"/> <xs:enumeration value="assessment_note"/> <xs:enumeration value="goals"/> <xs:enumeration value="health_concerns"/> <xs:enumeration value="referral"/> </xs:restriction> </xs:simpleType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> </xs:schema
Request CCDA: Request Example
<!-- for all categories between two dates --> <request> <username>dan</username> <action>requestCCDA</action> <startdate>2017-01-01</startdate> <enddate>2017-12-31</enddate> <category>all</category> </request> <!-- for all categories for the last encounter --> <request> <username>dan</username> <action>requestCCDA</action> <category>all</category> </request> <!-- for some categories --> <request> <username>dan</username> <action>requestCCDA</action> <startdate>1970-01-01</startdate> <enddate>2017-12-31</enddate> <category>problems</category> <category>medications</category> <category>allergies</category> <category>labs</category> <category>vitals</category> <category>procedures</category> </request>
Request CCDA: Reply Schema
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="reply"> <xs:complexType> <xs:sequence> <xs:element name="code" use="required"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="OK"/> <xs:enumeration value="FAIL"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element type="xs:string" name="message" use="required"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
Request CCDA: Reply Example
For success:
<reply>
<code>OK</code>
<message>CCDA request queued.</message>
</reply>
For failure:
<reply>
<code>FAIL</code>
<message>Unable to queue CCDA request.</message>
</reply>
Get List of CCDAs
Purpose and Use: Retrieve a list of stored CCDAs. The session id being passed in must in the http header with key sessionid. The apikey must be in the http header with key apikey.
Get List of CCDAs : Request Schema
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="request"> <xs:complexType> <xs:sequence> <xs:element type="xs:string" name="action" use="required" fixed="getListOfCCDA"/> <xs:element type="xs:string" name="username" use="required"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
Get List of CCDAs : Request Example
<request> <action>getListOfCCDA</action> <username>2234234234as1int-1800-01-01</username> </request>
Get List of CCDAs : Reply Schema
For success: <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="reply"> <xs:complexType> <xs:sequence> <xs:element type="xs:string" name="code" fixed="OK"/> <xs:element name="ccdas"> <xs:complexType> <xs:sequence> <xs:element type="xs:string" name="ccda" maxOccurs="unbounded" minOccurs="0"/> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> </xs:schema> For failure: <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="reply"> <xs:complexType> <xs:sequence> <xs:element type="xs:string" name="code" use="required" fixed="FAIL"/> <xs:element type="xs:string" name="message" use="required"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
Get List of CCDAs : Reply Example
For success: <reply> <code>OK</code> <ccdas> <ccda>jobid|encoded_information|status</ccda> <ccda>jobid|encoded_information|status</ccda> <ccda>jobid|encoded_information|status</ccda> <ccda>jobid|encoded_information|status</ccda> </ccdas> </reply> For failure: <reply> <code>FAIL</code> <message>Unable to retrieve data.</message> </reply> NOTE: The encoded information for the ccdas is also | delimited with creation date, data start date, data end date, and categories included in the CCDA. Example: 2017-01-01 12:31:39|2017-01-01|2017-12-31|ALL If the data is for the last encounter the data is as follows: 2017-01-01 12:31:39|||ALL NOTE: The status codes are as follows: 1 = queued 2 = running 3 = successfull 4 = no results 5 = downloaded 6 = expired 7 = deleted
Get CCDA
Purpose and Use: Retrieve a stored CCDA. The session id being passed in must in the http header with key sessionid. The apikey must be in the http header with key apikey.
Get CCDA : Request Schema
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="request"> <xs:complexType> <xs:sequence> <xs:element type="xs:string" name="action" use="required" fixed="getCCDA"/> <xs:element type="xs:string" name="jobid" use="required"/> <xs:element type="xs:string" name="username" use="required"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
Get CCDA : Request Example
<request> <action>getCCDA</action> <jobid>234j234-2sfjkasldfj-kjlskdjfsdf</jobid> <username>234234234as-1800-01-01</username> </request>
Get CCDA : Reply Schema
For success:
<xs:schema attributeFormDefault="unqualified"
elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="reply">
<xs:complexType>
<xs:sequence>
<xs:element type="xs:string" name="code" use="required"
fixed="OK"/>
<xs:element type="xs:string" name="ccda" use="required"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
For failure:
<xs:schema attributeFormDefault="unqualified"
elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="reply">
<xs:complexType>
<xs:sequence>
<xs:element type="xs:string" name="code" use="required"
fixed="FAIL"/>
<xs:element type="xs:string" name="message" use="required"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Get CCDA : Reply Example
For success: <reply> <code>OK</code> <ccda>encoded_compressed_ccda_data</ccda> <!-- decode and then decompress --> </reply> For failure: <reply> <code>FAIL</code> <message>Unable to retrieve data.</message> </reply>
Logout
Purpose and Use: Logs out of the system. The session id being passed in must in the http header with key sessionid. The apikey must be in the http header with key apikey.
Logout : Request Schema
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="request"> <xs:complexType> <xs:sequence> <xs:element type="xs:string" name="username" use="required" fixed="logout"/> <xs:element type="xs:string" name="action" use="required"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
Logout : Request Example
<request> <username>dan</username> <action>logout</action> </request>
Logout : Reply Schema
For success: <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="reply"> <xs:complexType> <xs:sequence> <xs:element type="xs:string" name="code" use="required" fixed="OK"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema> For failure: <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="reply"> <xs:complexType> <xs:sequence> <xs:element type="xs:string" name="code" use="required" fixed="FAIL"/> <xs:element type="xs:string" name="message" use="required"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
Logout : Reply Example
For success: <reply> <code>OK</code> </reply> For failure: <reply> <code>FAIL</code> <message>An error has occurred.</message> </reply>