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

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)

A Client should be

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

   Capable of receiving response in JSON and XML formats.

   Capable of downloading the response as a file.

   Capable of storing a Cookie.

   Capable of handling "https" connections.

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.

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:

    MRD Number (Unique Patient Identifier) in JSON format.

    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:

   The specific category(s) details in JSON format.

   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:

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

   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:

   Patient's clinical data in CCDA XML format.

   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 is available at

Terms and Conditions for API Usage