Managing ICD codes

The International Statistical Classification of Diseases and Related Health Problems (ICD) are medical diagnosis codes that classify diseases. These are also referred to as ICD codes. ICD codes are used to standardize information about the causes, symptoms, and diagnoses of medical issues. ClaimCenter provides over 72,000 ICD codes as reference data. These codes can be attached to claims, such as workers' compensation claims. ClaimCenter also provides a user interface for searching for, creating, and editing codes. For more information on the business functionality of ICD codes, refer to the Application Guide.

Cloud API also provides endpoints that you can use to manage ICD codes.

Querying for ICD codes

Use the following endpoint to retrieve all ICD codes loaded into ClaimCenter:

  • GET /admin/v1/icd-codes

Note: In the base configuration, there are over 72,000 ICD codes. By default, each GET returns a page of 25 codes. You can modify the default page size using the pageSize query parameter. But given the amount of codes, it is usually impractical to page through codes to identify a specific code. It is usually more efficient to search for a code. For more information, see Searching for ICD codes.

For example, the following query returns the first 2 codes.

Command

GET /admin/v1/icd-codes?pageSize=2

Response

{
    "count": 2,
    "data": [
        {
            "attributes": {
                "bodySystem": {
                    "code": "DIG",
                    "name": "Diseases of the digestive system (K00-K95)"
                },
                "code": "A00.0",
                "description": "Cholera due to Vibrio cholerae 01, biovar cholerae",
                "edition": {
                    "code": "ICD10",
                    "name": "ICD10"
                },
                "id": "icd10:A00.0"
            },
            ...
        },
        {
            "attributes": {
                "bodySystem": {
                    "code": "DIG",
                    "name": "Diseases of the digestive system (K00-K95)"
                },
                "code": "A00.1",
                "description": "Cholera due to Vibrio cholerae 01, biovar eltor",
                "edition": {
                    "code": "ICD10",
                    "name": "ICD10"
                },
                "id": "icd10:A00.1"
            },
            ...
        }
    ...

Use the following endpoint to retrieve a specific ICD codes:

  • GET /admin/v1/icd-codes/{icdCodeId}

For example, the following query returns information about ICD code icd10:A00.0.

Command

GET /admin/v1/icd-codes/icd10:A00.0

Response

{
    "data": {
        "attributes": {
            "bodySystem": {
                "code": "DIG",
                "name": "Diseases of the digestive system (K00-K95)"
            },
            "code": "A00.0",
            "description": "Cholera due to Vibrio cholerae 01, biovar cholerae",
            "edition": {
                "code": "ICD10",
                "name": "ICD10"
            },
            "id": "icd10:A00.0"
        },
        ...
    }
}

Searching for ICD codes

Use the following endpoint to search for ICD codes.

  • POST /admin/v1/search/icd-codes

When you call this endpoint, you must provide a body. The body can be empty, in which case all ICD codes are returned. (This is equivalent to executing GET /admin/v1/icd-codes.)

You can also specify one or more of the following fields:

  • activeDate- A date or datetime value, specified as a string, at which the ICD code is active. This returns any ICD code whose AvailabilityDate is on or after the given datetime and whose ExpiryDate is on or before the given datetime.

  • bodySystem - A typecode from the ICDBodysystem typelist, such as INF (Certain infectious and parasitic diseases (ICD10 A00-B99)). The search returns only ICD codes whose with that bodySystem code.

  • code - A String representing a portion of the ICD 10 code. The search returns only ICD codes whose code contains the specified String.

  • description - A String value. The search returns only ICD codes whose description contains the specified String.

  • edition - A typecode from the ICDEdition typelist. The search returns only ICD codes whose with that edition code.

bodySystem and description example

The following request searches for all ICD codes whose bodySystem code is DIG (Diseases of the digestive system (K00-K95)) and whose description includes the text "fever". The request returns only the ID, body system, and description of each code.

Command

POST /admin/v1/search/icd-codes?fields=id,bodySystem,description

Request

{
  "data": {
    "attributes": {
        "bodySystem": {
            "code": "DIG"
        },
        "description": "fever"
    }
  }
}

Response

{
    "count": 6,
    "data": [
        {
            "attributes": {
                "bodySystem": {
                    "code": "DIG",
                    "name": "Diseases of the digestive system (K00-K95)"
                },
                "description": "Typhoid fever, unspecified",
                "id": "icd10:A01.00"
            }
        },
        {
            "attributes": {
                "bodySystem": {
                    "code": "DIG",
                    "name": "Diseases of the digestive system (K00-K95)"
                },
                "description": "Typhoid fever with other complications",
                "id": "icd10:A01.09"
            }
        },
        {
            "attributes": {
                "bodySystem": {
                    "code": "DIG",
                    "name": "Diseases of the digestive system (K00-K95)"
                },
                "description": "Paratyphoid fever A",
                "id": "icd10:A01.1"
            }
        },
        {
            "attributes": {
                "bodySystem": {
                    "code": "DIG",
                    "name": "Diseases of the digestive system (K00-K95)"
                },
                "description": "Paratyphoid fever B",
                "id": "icd10:A01.2"
            }
        },
        {
            "attributes": {
                "bodySystem": {
                    "code": "DIG",
                    "name": "Diseases of the digestive system (K00-K95)"
                },
                "description": "Paratyphoid fever C",
                "id": "icd10:A01.3"
            }
        },
        {
            "attributes": {
                "bodySystem": {
                    "code": "DIG",
                    "name": "Diseases of the digestive system (K00-K95)"
                },
                "description": "Paratyphoid fever, unspecified",
                "id": "icd10:A01.4"
            }
        }
    ],
    ...
}

activeDate and description example

The following request searches for all ICD codes that are active on September 30, 2024 and whose description includes the text "fever". The request returns only the ID and description of each code. (Note that, in the base configuration, the ICD Codes do not have active and expiration dates. So in the base configuration, this would return all ICD Codes with "fever" in the description.)

Command

POST /admin/v1/search/icd-codes?fields=id,availabilityDate,expirationDate,description

Request

{
  "data": {
    "attributes": {
        "activeDate": "2024-09-30",
        "description": "fever"
    }
  }
}

Response

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "availabilityDate": "2024-09-15T00:00:00.000Z",
                "description": "Typhoid fever, unspecified",
                "expirationDate": "2024-10-15T00:00:00.000Z
",
                "id": "icd10:A01.00"
            }
        }
    ],
    ...
}

POSTing ICD codes

Use the following endpoint to POST an ICD code:

  • POST /admin/v1/icd-codes

The minimum required fields are:

  • bodySystem - A typecode from the ICDBodySystem typelist, such as INF (Certain infectious and parasitic diseases (ICD10 A00-B99))

  • code - A String of up to 8 characters representing the ICD 10 code

  • description - A String

Th following fields are optional:

  • availabilityDate - A date value identifying the first day the ICD code is available

  • chronic - A Boolean value which, if not specified, defaults to false

  • edition - A typecode from the ICDEdition typelist. In the base configuration, there is only one ICD Edition code: ICD10. Thus, new codes default to this edition

  • expirationDate - A date value identifying the last day the ICD code is available

For example, the following request creates a new ICD code.

Command

POST /admin/v1/icd-codes

Request

{
  "data": {
    "attributes": {
        "bodySystem": {
            "code": "INF"
        },
        "code": "AA77.07",
        "description": "Cabin fever"
    }
  }
}

Response

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "bodySystem": {
                    "code": "INF",
                    "name": "Certain infectious and parasitic diseases (ICD10 A00-B99)"
                },
                "chronic": false,
                "code": "AA77.07",
                "description": "Cabin fever",
                "edition": {
                    "code": "ICD10",
                    "name": "ICD10"
                },
                "id": "cc:Sh8KF2kE94Jt0ZGE91ejL"
            },
            ...
        }
    }
}

PATCHing ICD codes

Use the following endpoint to PATCH an ICD code:

  • PATCH /admin/v1/icd-codes/{icdCodeId}

For example, the following request modifies the code for the ICD Code created in the previous example.

Command

PATCH /admin/v1/icd-codes/cc:Sh8KF2kE94Jt0ZGE91ejL

Request

{
  "data": {
    "attributes": {
        "chronic": true
    }
  }
}

Response

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "bodySystem": {
                    "code": "INF",
                    "name": "Certain infectious and parasitic diseases (ICD10 A00-B99)"
                },
                "chronic": true,
                "code": "AA77.07",
                "description": "Cabin fever",
                "edition": {
                    "code": "ICD10",
                    "name": "ICD10"
                },
                "id": "cc:Sh8KF2kE94Jt0ZGE91ejL"
            },
            ...
        }
    }
}