API Developer Documentation

Amrita HIS API Server v7.0


1. Introduction

This document is a guide for developers who are creating applications for accessing Patient Health Information using Amrita HIS API.

2. API basics

The API is based on read-only HTTPS enabled RESTful URLs. All requests are in the following format, with parameters being passed as POST. The parameters depend on the type of API Name. The format of the URL is as shown below:

https://(baseUrl)/hisapi/(apiName)

3. Client Requirements

A Client should be

icon    Capable of sending POST requests as a RESTful URL along with the parameters.

icon    Capable of receiving response in JSON and XML formats.

icon    Capable of downloading the response as a file.

icon    Capable of storing a Cookie.

icon    Capable of handling "https" connections.

4. Authentication

Client authentication is performed using a username and password. These credentials can be obtained by contacting the health care facility directly. The login URL is as shown below, where baseURL is provided by the health care facility:

https://(baseURL)/hisapi/login

Following POST parameters are required for this call:

Name
Data Type
Mandatory
User Name String Yes
Password String Yes
Table 1: Parameters - Login

The credentials are verified by the server and a security token ('Credential' cookie) is sent back on successful validation. All the subsequent requests are required to pass this token. If the access token is missing or expired, the API will return the following code: HTTP Status 401 Unauthorized response.

5. API Specification

a. Patient Selection Query


The patient selection URL is as shown below:

https://(baseUrl)/hisapi/getPatient

Following POST parameters are supported for this call:

Name
Data Type
Mandatory
First Name String Yes
Middle Name String No
Last Name String Yes
Dob Date Yes
Sex String Yes
Address 1 String Yes
Address 2 String No
City String Yes
State String Yes
Country String Yes
Zip Code String Yes
CellPhone String Yes
HomePhone String Yes
OfficePhone String No
Table 2: Parameters - Patient Selection

Following are the return variables and status:

icon     MRD Number (Unique Patient Identifier) in JSON format.

icon     HTTP 200 OK Status

Following are the exception handling details for this call:

Exception
Data Type
Mandatory
NoPatientWithProvidedCriteria No Patient with provided criteria present Exception thrown when there is no patient matching this criterion.
UnsupportedSex Unsupported 'Sex' passed as parameter Exception thrown when 'sex' other than 'Male (M)', 'Female (F)' or 'Unknown (UNK)' is passed as a parameter.
InvalidState Provided state doesn't exist Exception thrown when an invalid 'State' is passed as a parameter
InvalidCountry Provided country doesn't exist Exception thrown when an invalid 'Country' is passed as a parameter
Table 3: Exceptions - Patient Selection

b. Query based on Categories

The URL for getting the data based on categories is as shown below:

https://(baseUrl)/hisapi/viewCCDACategories

Following POST parameters are supported for this call:

Name
Description
Data Type
Mandatory
mrdNumber Unique patient identifier String Yes
DateFormat Date format used at the client site. String Yes
FromDate Date No
ToDate Date No
Category CCDS category is required. Refer Table 5 for a list of supported categories. This can be a comma separated list in case multiple categories need to be queried. String Yes
Table 4: Parameters - View CCDA Categories

Following categories are supported:

Common Clinical Data Set Element
Category
Patient Name Patient Name
Sex Gender
Date of Birth DOB
Race Race
Ethnicity Ethnicity
Preferred Language PreferredLanguage
Smoking Status SmokingStatus
Problems Problems
Medications Medications
Medication Allergies MedicationAllergies
Laboratory Tests LaboratoryTests
Laboratory Values(s)/Result(s) LaboratoryResult
Vital Signs VitalSigns
Procedures Procedures
Care Team Member(s) CareTeamMembers
Immunizations Immunizations
Unique Device Identifier(s) for a Implantable Device(s) Implants
Assessment and Plan of Treatment Assessment
Goals Goals
Health Concerns HealthConcerns
Table 5: CCDA Categories

Following are the return variables and status:

icon    The specific category(s) details in JSON format.

icon    HTTP 200 OK Status

Following are the exception handling details for this call:

Exception
Message
Description
DataCategoryEmpty Please provide at least one valid CCDS data category Exception thrown when no category is passed as parameter.
DataCategoryInvalid Not a valid CCDS data category Exception thrown when an unsupported category is passed as a parameter.
Table 6: Exceptions - View CCDA Categories

c. Query based on categories for a Specific Date or Date Range (Dates are not mandatory)


The CCDS data categories can be queried based on dates by using the above API and specifying either:

icon    Specific Date: Same date in 'fromDate' and 'toDate' parameters

icon    Date Range: Different dates in 'fromDate' and 'toDate' parameters.

d. Query for a CCDA document

Patient's clinical data in CCDA format can be obtained by using the following URL:

https://(baseUrl)/hisapi/viewCCDA

Following POST parameters are supported for this call:

Name
Data Type
Mandatory
docType String Yes
mrdNumber String Yes
dateFormat String Yes
fromDate Date No
toDate Date No
Table 7: Parameters - View CCDA

Following are the return variables and status:

icon    Patient's clinical data in CCDA XML format.

icon    HTTP 200 OK Status

Following are the exception handling details for this call:

Exception
Message
Description
EMR-GenCCDAFailed_Exception-E Failed to generate summary care document. Exception thrown when CCDA document generation fails.
Table 8: Exceptions - View CCDA

Terms of Use

Terms of Use is available at

About Amrita Medical

Amrita Medical Solutions is the resultant creative effort of a dedicated team of physicians, nurses, medical technologists, software and hardware engineers and other healthcare professionals, over the last ten years. Read more

Contact Us

Amrita Ventures Inc.
10200 Crow Canyon Road, Suite 590
Castro Valley CA, 94552

    262-707-8192
     info@amritamedical.com