×
schedule your live demo
More

Sevocity EHR API Version 1.1

This documentation provides access information for searching and fetching patient data utilizing Sevocity EHR APIs in accordance to the regulations cited by ONC in § 170.315(g)(7) and § 170.315(g)(9)(Cures Update). 

Terms and Conditions

Terms and Conditions of Use 

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>