What is Diagnosis API?
SmrtX provides an API (Application Programming Interface) for patient preliminary medical diagnosis that can help you implement an intelligent symptom checker and Lab Test analyzer for your healthcare medical application.
When you incorporate Diagnosis API within your healthcare web-application it will have the same functionalities like presented in DDxHub Diagnosis System. This is an alive example of implementation. By testing the DDxHub Diagnosis System you can see how global companies, as well as startups, have used it to enhance their business and support surrounding their patients and healthcare organizations.

When you transmit to our web service a basic patient health data (such as Blood test results and symptoms), our AI inference engine will analyze the data and provide you with a list of the most likely health conditions. We get this according to the complex statistical algorithms we use to make medical diagnosis.

Introduction
Setup
The current version of the Diagnosis API is available at https://diagnosisapi.azurewebsites.net. It is a standard web service (Web API) that accepts GET and POST requests. All responses (including error messages) use the JSON format. POST requests also take JSON inputs (make sure you include the header Content-Type: application/json).

Authentication
The Diagnosis API uses custom HTTP header to authenticate your requests. You will need to add AuthenticationID header to every request you make. For your Demo Development you can use AuthenticationID = DEMO_AuthenticationID. We will provide you with your unique AuthenticationID value after you made a production order registration.

First request
The most important part of the API, which handles medical diagnostics, is the /api/DDxItems/ endpoint, which accepts POST requests. Apart from laboratory test results, it requires a list of observed symptoms. The lists cannot be empty, so first you need to collect an initial information to run diagnosis.

Let’s assume we have a patient, suffering from strong smell urine, frequent urination and yellow skin. Each observation is represented by a unique ID; in this case the symptom IDs are 164, 151 and 200, respectively. Also the patient has list of implemented Lab Test Procedures: ALT, Amalyse, AST, Total Bilirubin, GT Chlamydia, Appearance Urine, and ABO grouping. By entering and identified the tests values you can send (POST) both Symptoms and Tests lists to https://diagnosisapi.azurewebsites.net. Then GET Possible Health Conditions from the Diagnosis API.

In order to achieve best results and enable more features of the API, you have to provide as many test result and symptoms as possible. This will depend on the accuracy of the diagnoses obtained. The case described above can be represented with the following JSON object:

JSON for Symptoms List
[
{“ID”:164},
{“ID”:151},
{“ID”:200}
]

JSON for Tests List
[
{“ID”:43,“Value”:“66”,“LowRangeValue”:“8”,“HighRangeValue”:“40”,“ReferenceType”:0},
{“ID”:44,“Value”:“110”,“LowRangeValue”:“23”,“HighRangeValue”:“85”,“ReferenceType”:0},
{“ID”:45,“Value”:“1”,“LowRangeValue”:“10”,“HighRangeValue”:“45”,“ReferenceType”:0},
{“ID”:47,“Value”:“22”,“LowRangeValue”:“0.2”,“HighRangeValue”:“1”,“ReferenceType”:0},
{“ID”:132,“Value”:“Negative”,“LowRangeValue”:“0”,“HighRangeValue”:“0”,“ReferenceType”:0},
{“ID”:175,“Value”:“0”,“LowRangeValue”:“0”,“HighRangeValue”:“0”,“ReferenceType”:0},
{“ID”:114,“Value”:“B”,“LowRangeValue”:“0”,“HighRangeValue”:“0”,“ReferenceType”:0}
]

Your first request to the API could look like this:

cURL
curl ‘https://diagnosisapi.azurewebsites.net/api/DDxItems/?AuthenticationID=DEMO_AuthenticationID’
-X “POST”
-H “Content-Type: application/json” -d ‘{
“id”:“9999”,
“tests”:"[{“ID”:43,“Value”:“66”,“LowRangeValue”:“8”,“HighRangeValue”:“40”,“ReferenceType”:0},{“ID”:44,“Value”:“110”,“LowRangeValue”:“23”,“HighRangeValue”:“85”,“ReferenceType”:0},{“ID”:45,“Value”:“1”,“LowRangeValue”:“10”,“HighRangeValue”:“45”,“ReferenceType”:0},{“ID”:47,“Value”:“22”,“LowRangeValue”:“0.2”,“HighRangeValue”:“1”,“ReferenceType”:0},{“ID”:132,“Value”:“Negative”,“LowRangeValue”:“0”,“HighRangeValue”:“0”,“ReferenceType”:0},{“ID”:175,“Value”:“Cloudy”,“LowRangeValue”:“0”,“HighRangeValue”:“0”,“ReferenceType”:0},{“ID”:114,“Value”:“B”,“LowRangeValue”:“0”,“HighRangeValue”:“0”,“ReferenceType”:0}]",
“symptoms”:"[{“ID”:164},{“ID”:151},{“ID”:200}]"
}’

Output
After you successfully send the POST request, Diagnosis API system starts to generate list of Possible Health Conditions. You can retrieve the suggested diagnoses list by applying GET request:
https://diagnosisapi.azurewebsites.net/api/DDxItems/9999?AuthenticationID=DEMO_AuthenticationID
This is the last GET request listed in https://www.postman.com/collections/7445d89fda1d633e08dd Postman collection provided by us.
The 9999 is Id supplied with your POST statement. Please generate unique Ids since your clinical decision system’s users may access simultaneously. You have to replace the DEMO_AuthenticationID with your production registered ID.

The response returned from https://diagnosisapi.azurewebsites.net/api/DDxItems/ will contain diagnosis according to the following structure:
long Id
string Name
string Description
string ICD9
string ICD10
string ICD11
int Weight
TestGetType Tests
int ID
bool Entered
string Value
string Status
string UnitsType
string LowRangeValue
string HighRangeValue
string UnitsTypeSI
string LowRangeValueSI
string HighRangeValueSI
string ComboValuesList
string NegativeComboValue
string Comment
int ReferenceType
SymptomGetType Symptoms
int ID
string Symptom
bool Entered
string SimilarSymptomsList
string Category

So that represents list of possible health conditions (Diseases) described by the parameters above. Most possible disease ranked on the top of the list.
The output JSON looks like the following:
[
{“id”:1,
“name”:“Metabolic acidosis”,
“description”:"…description listed here…",
“icD9”:“276.2”,
“icD10”:“E87.2”,
“icD11”:“5C73”,
“weight”:15,
“tests”:"[
{“ID” : 119, “Entered” : true, “Value” : “220”, “Status” : “High”, “UnitsType” : “mmol/L”, “LowRangeValue” : “98”, “HighRangeValue” : “109”, “UnitsTypeSI” : “”, “LowRangeValueSI” : “0”, “HighRangeValueSI” : “0”, “ComboValuesList” : “”, “NegativeComboValue” : “”, “Comment” : “”, “ReferenceType” : 0},
{“ID” : 212,“Entered” : false,“Value” : “”,“Status” : “Low”,“UnitsType” : “unitless”,“LowRangeValue” : “7.34”,“HighRangeValue” : “7.44”,“UnitsTypeSI” : “”,“LowRangeValueSI” : “0”,“HighRangeValueSI” : “0”,“ComboValuesList” : “”,“NegativeComboValue” : “”,“Comment” : “”,“ReferenceType” : 0},
{“ID” : 213,“Entered” : false,“Value” : “”,“Status” : “Low”,“UnitsType” : “mEq/L”,“LowRangeValue” : “22”,“HighRangeValue” : “26”,“UnitsTypeSI” : “”,“LowRangeValueSI” : “0”,“HighRangeValueSI” : “0”,“ComboValuesList” : “”,“NegativeComboValue” : “”,“Comment” : “”,“ReferenceType” : 0},
{“ID” : 214,“Entered” : false,“Value” : “”,“Status” : “Low”,“UnitsType” : “mmHg”,“LowRangeValue” : “35”,“HighRangeValue” : “45”,“UnitsTypeSI” : “”,“LowRangeValueSI” : “0”,“HighRangeValueSI” : “0”,“ComboValuesList” : “”,“NegativeComboValue” : “”,“Comment” : “”,“ReferenceType” : 0}]",
“symptoms” : “[
{“ID” : 1,“Symptom” : “rapid breathing”,“Entered” : false,“SimilarSymptomsList” : “”,“Category” : “”},
{“ID” : 2,“Symptom” : “lethargy”,“Entered” : false,“SimilarSymptomsList” : “”,“Category” : “”},
{“ID” : 3,“Symptom” : “confusion”,“Entered” : false,“SimilarSymptomsList” : “”,“Category” : “”}]”
},
{“id”:138,
“name”:“Renal Tubular Acidosis”,
“description”:"…description listed here…",
“icD9”:“588.89”,
“icD10”:“N25.89”,
“icD11”:“GB90.44”,
“weight”:15,
“tests”:"[…Tests listed here…]",
“symptoms”:"[…Symptoms listed here…]"
},
{“id”:139,
“name”:“Fanconi syndrome”,
“description”:"…description listed here…",
“icD9”:“270.0”,
“icD10”:“E72.00”,
“icD11”:“GB90.42”,
“weight”:15,
“tests”:"[…Tests listed here…]",
“symptoms”:"[…Symptoms listed here…]"
}
]

Diagnosis API is available as the Postman collection. The collection includes some endpoints and predefined requests that you can extend. It allows you to test the API in seconds. We have created a sample “Diagnosis API” collection for you. The collection located: https://postman.com/collections/7445d89fda1d633e08dd

! Please note: Correct med-statistics data is not provided for Demo Development.

Next steps
You should now have an initial understanding of how to work with the Diagnosis API. Feel free to read the subsequent sections of this documentation for detailed information, or go to our GitHub to see sample MVC web-application built to help you better understand the Diagnosis API usage.

Outlines
The Diagnosis API is available at https://diagnosisapi.azurewebsites.net. All requests to the API must be made via HTTPS. The API hosted on Azure storage. Azure Storage currently supports three versions of the TLS protocol: 1.0, 1.1, and 1.2. Azure Storage uses TLS 1.2 on public HTTPS endpoints, but TLS 1.0 and TLS 1.1 are still supported for backward compatibility.
Also, that provides cross-origin resource sharing (CORS) to allow client-side code of web applications to interact with the Diagnosis API, but please make sure you never expose your API credentials in any client-side code of public websites.

HTTP Methods
The Diagnosis API can be easily integrated with any existing HTTP client by using any popular programming languages and frameworks. The API content is read-only and all of the API responses always return the same output for the same input, no matter how many times you call them. As any RESTfull service, the API supports four HTTP methods: DELETE, PUT, GET, and POST. However, you need to use only two last of them.
Use GET requests to retrieve data that do not require any data to be sent in the request’s body.
Use POST requests for actions that require data to be sent in the request’s body (e.g. /api/DDxItems).

JSON
JSON is the only data format supported by Diagnosis API. All of our endpoints return JSON objects or lists. Moreover, the POST actions expect request bodies formatted as JSON objects. Error messages are also in JSON. Requests, like responses, should be encoded in UTF-8.

Authentication
Diagnosis API uses a custom authentication mechanism. Each request must include non-standard HTTP header: AuthenticationID. This parameter corresponds to your unique application ID. For your Demo Development you can use AuthenticationID = DEMO_AuthenticationID. We will provide you with your unique AuthenticationID after registration.
An example of a request could look like this (finally you will replace DEMO_AuthenticationID with your credentials):
‘https://diagnosisapi.azurewebsites.net/api/DDxItems/?AuthenticationID=DEMO_AuthenticationID’

Base Health Terms
Diagnostic information recognized by the API engine is categorized as Lab Test Procedures and Symptoms. To take advantage of the diagnostic capabilities of Diagnosis API you must describe your patient cases in terms of observations available in the presented model; in other words, you need to know exact Test results and Symptoms to be passed to the /DDxItems endpoint.
For each medical concept category there are two REST-inspired read-only endpoints supporting GET requests:
one returns the list of all Lab Tests Procedures (https://diagnosisapi.azurewebsites.net/api/DDxItems/GetTests?AuthenticationID=DEMO_AuthenticationID),
the other returns the list of all possible Symptoms (https://diagnosisapi.azurewebsites.net/api/DDxItems/GetSymptoms?AuthenticationID=DEMO_AuthenticationID).

Each concept is represented by a JSON object with several attributes. Some attributes are common to both concepts:
id – short and unique concept (test or symptom) id,
name – concept name (professional medical term),
description – detailed description.

Test Procedures
Laboratory Tests in API presented as the following structure:
int id
string procedure
string LowRangeValue
string HighRangeValue
string UnitsType
string LowRangeValueSI
string HighRangeValueSI
string UnitsTypeSI
string ComboValuesList
string NegativeComboValue
string descriptionLow
string descriptionHigh
string sid

Example of a JSON object representing test procedure with id = 11, as returned by https://diagnosisapi.azurewebsites.net/api/DDxItems/GetTest/11?AuthenticationID=DEMO_AuthenticationID
[{“id”:11,
“procedure”:“Hematocrit”,
“lowRangeValue”:"-100",
“highRangeValue”:“100”,
“unitsType”:"%",
“lowRangeValueSI”:“40”,
“highRangeValueSI”:“51”,
“unitsTypeSI”:"%",
“comboValuesList”:"",
“negativeComboValue”:"",
“descriptionLow”:"[DEMO]",
“descriptionHigh”:"[DEMO]",
“sid”:“1.2.4”}]

Please take a look at how Tests Edit interface implemented in DDxHub web-application.

Symptoms
Symptoms represent medical signs. Symptoms in the API model are organized into Categories: Breathing, Muscles, Blood and so on. Symptoms in API presented as the following structure:
int id
string Symptom
string SimilarSymptomsList
string Category

Example of a JSON object representing symptom with id = 11, as returned by https://diagnosisapi.azurewebsites.net/api/DDxItems/GetSymptom/11?AuthenticationID=DEMO_AuthenticationID
[{“id”:11,
“symptom”:“muscle twitching”,
“similarSymptomsList”:"[DEMO… data available in registered version]",
“category”:“Muscles”}
]

Please take a look at how Symptoms Edit interface implemented in DDxHub web-application.

-* ! Please note: Correct med-statistics data is not provided for Demo Development*.