Terminology - Classify

The Classify Terminology API takes an input coding and provides a set of classifications based on the domain. For example, a medication code may be classified by its ingredient(s) and strength, while a condition is classified by category and whether it is acute or chronic.

Contents

Overview
Classifications
Operations
Batch Operations

Overview

Each domain has its own classify operation, but they all work in a similar manner. In the body parameters of the request, you provide the code and system for the input coding. You may optionally provide a display value. For example:

Sample Classify Input

{
    "code": "861004",
    "system": "RxNorm"
}

The Terminology service will then classify the input coding into a set of domain-specific classifications.

Sample Classify Output

{
    "medRtTherapeuticClass": [
        "Blood Glucose Regulators"
    ],
    "rxNormIngredient": [
        "metformin"
    ],
    "rxNormStrength": "1000MG",
    "rxNormGeneric": true,
    "immunization": false,
    "covid19Rx": null
}

Note
The code must be from a code system applicable to the domain, as specified by each operation. For example, a medication code must come from RxNorm, SNOMED, or one of the other reference code systems listed in the Classify Medication operation.

Classifications

The classifications in the response data are represented as a set of key/value pairs. The values can take several forms, depending on the domain:

String(s) - A simple string or a list of strings (e.g., RxNorm ingredients).
Codeable Concept - A coding represented by a code, code system, and display value (e.g., HCC Category).
Boolean - A true or false value (e.g., whether a condition is acute).
Categorical - A string value with a defined set of possible values (e.g., types of COVID-19 lab reports).

If a particular classification was not found for the given input, the value for that key will be null.

Operations

The following classify operations are available:

Operation	Input Reference Code Systems
Condition Provides clinical categories, acute vs. chronic, risk adjustment categories, and COVID status.	ICD-10-CM ICD-9-CM-Diagnosis SNOMED
Medication Provides RxNorm properties, MEDRT therapeutic class, and COVID-related category (including vaccination).	RxNorm NDC CVX SNOMED
Observation Provides LOINC properties and COVID test type.	LOINC SNOMED

Alternatively, you can use the $classify operation which is a superset of the individual domain-specific classify operations.

Batch Operations

Every classify operation supports a batch mode to classify multiple terminology codings at once.

POST /terminology/v1/classify/{type}/batch

The input data contains an items array with the codings to classify.

The output data will then contain an items array with the usual classify output for each item.

Tip
The output items will be in the same order as the input items.

For example: /terminology/v1/classify/condition/batch

Sample Batch Input

{
    "items": 
    [
        {
            "code": "119981000146107",
            "system": "SNOMED"
        },
        {
            "code": "J45.50",
            "system": "ICD-10-CM"
        }   
    ]
}

Sample Batch Output

{
    "items": [
        {
            "ccsrCategory": {
                "coding": [
                    {
                        "system": "CCSR Category",
                        "code": "INF012",
                        "display": "Coronavirus disease – 2019 (COVID-19)"
                    }
                ]
            },
            ...
        },
        {
            "ccsrCategory": {
                "coding": [
                    {
                        "system": "CCSR Category",
                        "code": "RSP009",
                        "display": "Asthma"
                    }
                ]
            },            
            ...
        }
    ]
}