Severity Scoring Decision Support Tool API

API Reference

Surgisphere has developed an application program interface (API) for our popular COVID-19 severity scoring tool. This decision support tool, in use at thousands of hospitals on six continents, aids front line healthcare professionals gauge the severity of COVID-19.

This API is organized around REST, uses a predictable URL to code for key variables, permits form-encoded data, and does not require any authentication.

A Verbose form is available for debugging purposes. Partner organizations have the opportunity to contribute their data to our rapidly growing repository on COVID-19 patients through an opt in parameter. No protected health information (PHI) is ever stored.

This post describes the parameters and use of this API. Please notify us if you integrate this API into your clinical workflow. There is no charge for access to these services. Please review our Terms and Conditions of use on our website: in summary, use of this API does not replace consultation with a physician and Surgisphere does not make or claim any warranty or guarantee through the use of this tool.

Base URL and Format

You can use the sample request to the right to get started right away. The base URL always stays the same. In standard PHP format, there are 18 variables that follow. The API is designed to fail gracefully, but there are important notes below on default assumptions the API makes if there are missing values.

Copy to Clipboard

Overview of Variables

There are 18 key variables, defined below. Each variable is defined as optional or required, and default behavior is defined. The acceptable parameters for each variable are also provided.

Verbose is provided for debugging purposes and will provide detailed output on how variables may be changed.

Store is provided for opt in data sharing. The query you generate will be stored in our database and added to our repository. No protected health information (PHI) is stored as part of this process.

Variable: CAD

CAD is a binary variable. If a value is not specified or the field is not included, this variable will default to 0.

If a non-binary value is provided, this variable will default to 0.

Be aware that defaulting this variable to 0 can have unintended consequences on the quality of the severity score, potentially leading to a lower severity score than is appropriate. It is recommended that this variable be included to improve the quality of the severity score.

Coronary Artery Disease

Binary variable. Recommended / Optional.

Includes history of cardiovascular disease, coronary artery disease, myocardial infarction, congestive heart failure, arrhythmias, and peripheral artery disease. Condition should be present on admission.

Variable: HTN

HTN is a binary variable. If a value is not specified or the field is not included, this variable will default to 0.

If a non-binary value is provided, this variable will default to 0.

Be aware that defaulting this variable to 0 can have unintended consequences on the quality of the severity score, potentially leading to a lower severity score than is appropriate. It is recommended that this variable be included to improve the quality of the severity score.

Hypertension

Binary variable. Recommended / Optional.

History of hypertension, with or without treatment with medications. Condition should be present on admission.

Variable: DM

DM is a binary variable. If a value is not specified or the field is not included, this variable will default to 0.

If a non-binary value is provided, this variable will default to 0.

Be aware that defaulting this variable to 0 can have unintended consequences on the quality of the severity score, potentially leading to a lower severity score than is appropriate. It is recommended that this variable be included to improve the quality of the severity score.

Diabetes

Binary variable. Recommended / Optional.

History of diabetes mellitus, with or without the use of medications. Excludes diabetes insipidus. Condition should be present on admission.

Variable: COPD

COPD is a binary variable. If a value is not specified or the field is not included, this variable will default to 0.

If a non-binary value is provided, this variable will default to 0.

Be aware that defaulting this variable to 0 can have unintended consequences on the quality of the severity score, potentially leading to a lower severity score than is appropriate. It is recommended that this variable be included to improve the quality of the severity score.

Chronic Obstructive Pulmonary Disease / Asthma

Binary variable. Recommended / Optional.

History of COPD, bronchitis, emphysema, asthma, or other reactive airway disease.

Variable: Smoker

Smoker is a binary variable. If a value is not specified or the field is not included, this variable will default to 0.

If a non-binary value is provided, this variable will default to 0.

Be aware that defaulting this variable to 0 can have unintended consequences on the quality of the severity score, potentially leading to a lower severity score than is appropriate. It is recommended that this variable be included to improve the quality of the severity score.

Current Smoker

Binary variable. Recommended / Optional.

Current smoker, inclusive of cigarettes, cigars, vaping, or other substances. Excludes patients who are former smokers who quit prior to admission.

Variable: IC

IC is a binary variable. If a value is not specified or the field is not included, this variable will default to 0.

If a non-binary value is provided, this variable will default to 0.

Be aware that defaulting this variable to 0 can have unintended consequences on the quality of the severity score, potentially leading to a lower severity score than is appropriate. It is recommended that this variable be included to improve the quality of the severity score.

Immunocompromised

Binary variable. Recommended / Optional.

Includes a variety of conditions that lead to an immunocompromised, including but not limited to cancer, chemotherapy, steroid use, acquired or genetic conditions, transplant recipient, and the use of various other medications.

Variable: TB

TB is a binary variable. If a value is not specified or the field is not included, this variable will default to 0.

If a non-binary value is provided, this variable will default to 0. We recognize that many healthcare systems will not track this value. Missing values should default to 0.

The presence of tuberculosis as defined to the right should be coded as 1, as it affects the severity scoring in certain circumstances.

Tuberculosis

Binary variable. Recommended / Optional.

Includes patients with a history of tuberculosis or current infection.

Variable: Dyspnea

Dyspnea is a binary variable. If a value is not specified or the field is not included, this variable will default to 0.

If a non-binary value is provided, this variable will default to 0.

Be aware that defaulting this variable to 0 can have unintended consequences on the quality of the severity score, potentially leading to a lower severity score than is appropriate. It is recommended that this variable be included to improve the quality of the severity score.

While many of the variables above can be sourced from the EHR, Dyspnea will require specific entry unless natural language processing is enabled on your platform.

Shortness of Breath

Binary variable. Recommended / Optional.

Includes patients with a subjective complaint of shortness of breath, or exam findings consistent with dyspnea. Includes both acute and chronic findings.

Variable: Age

Age is an integer variable. If a value is not specified or the field is not included, this variable will default to -1 and lead to an error.

If a non-binary value is provided, this variable will default to -1 and lead to an error.

Age (Years)

Integer variable. Required.

Patient age, in years.

Variable: Temp

Temp is a floating point variable. If a value is not specified or the field is not included, this variable will default to -1 and lead to an error. Temperature must be provided in Celsius and no conversion is done from Fahrenheit to Celsius.

If a non-binary value is provided, this variable will default to -1 and lead to an error.

Temperature (Celsius)

Floating variable. Required.

Patient temperature, in celsius.

Variable: Pulse

Pulse is an integer variable. If a value is not specified or the field is not included, this variable will default to -1 and lead to an error.

If a non-binary value is provided, this variable will default to -1 and lead to an error.

Heart Rate (beats per minute)

Integer variable. Required.

Patient’s pulse, in beats per minute.

Variable: RR

RR is an integer variable. If a value is not specified or the field is not included, this variable will default to -1 and lead to an error.

If a non-binary value is provided, this variable will default to -1 and lead to an error.

Respiratory Rate (breaths per minute)

Integer variable. Required.

Patient’s respiratory rate, in breaths per minute.

Variable: O2

O2 is an integer variable. If a value is not specified or the field is not included, this variable will default to -1 and lead to an error.

If a non-binary value is provided, this variable will default to -1 and lead to an error.

Oxygen Saturation (%)

Integer variable. Required.

Patient’s oxygen saturation as an integer (i.e. 99). Do not provide as percent (99%) or decimal (0.99).

Variable: AVPU

AVPU is an ordinal variable presented as an integer. If a value is not specified or the field is not included, this variable will default to -1 and lead to an error.

If a value outside the range is provided, this variable will default to -1 and lead to an error.

While many of the variables above can be sourced from the EHR, AVPU will require specific entry unless natural language processing or SNOMED translation of structured exam findings is enabled on your platform.

Alert, Verbal, Pain, Unresponsive

Integer variable. Required.

Patient’s level of responsiveness to stimuli. If patient is alert (but not necessarily oriented), responsive only to verbal stimuli, responsive only to painful stimuli, or entirely unresponsive.

Variable: Ausc

Ausc is an ordinal variable presented as an integer. If a value is not specified or the field is not included, this variable will default to -1 and lead to an error.

If a value outside the range is provided, this variable will default to -1 and lead to an error.

While many of the variables above can be sourced from the EHR, Ausc will require specific entry unless natural language processing or SNOMED translation of structured exam findings is enabled on your platform.

Chest Auscultation

Integer variable. Required.

Physical examination findings upon auscultation of the chest. Options include the patient being clear to auscultation bilaterally, the presence of mild findings (intentionally subjective), or the presence of severe findings (intentionally subjective).

Variable: Amb

Amb is an ordinal variable presented as an integer. If a value is not specified or the field is not included, this variable will default to -1 and lead to an error.

If a value outside the range is provided, this variable will default to -1 and lead to an error.

While many of the variables above can be sourced from the EHR, Amb will require specific entry unless natural language processing or SNOMED translation of structured exam findings is enabled on your platform.

Ambulatory Status

Integer variable. Required.

Patient’s present ambulatory status, which includes 1) the ability to ambulate without assistance, 2) the ability to ambulate with assistance, and 3) unable to ambulate and restricted to gurney.

Variable: Store

Store is a binary variable. If a value is not specified or the field is not included, this variable will default to 0.

If a non-binary value is provided, this variable will default to 0.

This variable is intended to provide an opt-in mechanism for data to be stored in our database. Your responses help us gauge how this tool is being used and help to continue to improve the machine learning algorithms through continuous feedback. No protected health information is stored. If you do not specify the value of Store, it defaults to 0 and no data is saved.

Save to Database

Binary variable. Optional.

API query is stored to the database.

Variable: Verbose

Verbose is a binary variable. If a value is not specified or the field is not included, this variable will default to 0.

If a non-binary value is provided, this variable will default to 0.

This variable is intended to provide output to aid with testing and debugging. It should not be used in a production environment.

Debugging

Binary variable. Optional.

Verbose output is provided to assist with debugging in a test environment.

Output

Provides a numerical value to grade the degree of severity from 1-3. If an error is encountered, a value of -1 is provided. You should develop appropriate error handling if a non-ordinal value from 1-3 is returned.

Mild / moderate (1) indicates that limited supportive care may be necessary. Cases can range from observation status to routine bed, but physician discretion is necessary.

Severe (2) indicates that oxygen and further treatment are likely. A monitored bed is recommended.

Critical (3) indicates that intensive care and/or mechanical ventilation are very likely. The patient should be immediately assessed and monitored.

Result

Integer variable.

Provides a response code if error (-1), or degree of severity if no error (1-3).

Test Case 1

This test case is intended to return a code of '1'.

All variables are defined, Verbose is on, and Store is off.

Input

Copy to Clipboard

Output

Test Case 2

This test case is intended to return a code of '2'.

All variables are defined, Verbose is on, and Store is off.

Input

Copy to Clipboard

Output

Test Case 3

This test case is intended to return a code of '3'.

All variables are defined, Verbose is off, and Store is off.

Input

Copy to Clipboard

Output

Test Case 4

This test case is intended to return a code of '-1'.

All variables are defined, Verbose is off, and Store is off.

Input

Copy to Clipboard

Output

Get started with our industry leading solutions today

Looking for help? Get in touch with us