ICD-10 Validation in Python — Medical Diagnosis Codes

1. What is ICD-10?

ICD-10 is the 10th revision of the International Classification of Diseases, a standardised taxonomy of diseases, injuries, and causes of death maintained by the World Health Organization. First published in 1992, ICD-10 is used in more than 100 countries for mortality reporting, morbidity surveillance, clinical documentation, and healthcare reimbursement.

Each ICD-10 code represents a single diagnosis, condition, or cause of death. Codes are organised into 22 chapters covering broad body systems and disease categories. The WHO base classification has around 14,000 categories; the US clinical modification extends this to over 70,000 billable codes.

ICD-10 codes appear throughout healthcare data: electronic health records (EHRs), HL7 messages, FHIR Condition resources, insurance claims, cancer registries, and international cause-of-death reports. Validating them — both syntactically and against the current official dictionary — is essential for claim acceptance, interoperability, and data quality.

2. Code structure

An ICD-10 code has a well-defined prefix structure:

The first character is a letter (A–Z, excluding U which is reserved by WHO). The next two characters are digits forming the category. An optional decimal point followed by one to four additional characters specifies sub-categories and clinical detail.

3. WHO ICD-10 vs ICD-10-CM

There is not one ICD-10 dataset but several national clinical modifications:

4. Why ICD-10 validation matters

5. The right solution

The IsValid ICD-10 API validates both format and existence against a locally-maintained copy of the NIH/NLM ICD-10-CM dataset (refreshed monthly).

Full parameter reference: ICD-10 Validation API docs →

6. Python code example

Install with pip install isvalid-sdk or pip install requests.

Validate a single ICD-10 code:

# icd10_validator.py
import os
from isvalid_sdk import IsValidConfig, create_client

iv = create_client(IsValidConfig(api_key=os.environ["ISVALID_API_KEY"]))

# ── Validate an ICD-10 code ─────────────────────────────────────────────────

result = iv.icd10("J45.0")

if not result["found"]:
    print("Code is not in the ICD-10-CM dictionary")
else:
    print(f"Title: {result['title']}")     # → 'Predominantly allergic asthma'
    print(f"Chapter: {result['chapter']}") # → 'J'
    print(f"Parent: {result['parent']}")   # → 'J45'
    print(f"Leaf: {result['isLeaf']}")     # → True (billable)

Expand a parent code into its children:

# List all sub-categories of asthma (J45)
def list_children(parent: str) -> list[dict]:
    response = requests.get(
        f"{BASE_URL}/v0/icd10/children",
        params={"code": parent},
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    response.raise_for_status()
    return response.json()


for c in list_children("J45"):
    print(f"  {c['icd10']} — {c['title']}")
# → J45.0 Predominantly allergic asthma
# → J45.1 Nonallergic asthma
# → J45.2 Mild intermittent asthma
# ...

import asyncio
import httpx

async def scrub_claim(claim: dict, client: httpx.AsyncClient) -> dict:
    """Validate every diagnosis on a claim concurrently."""
    async def check(dx):
        r = await client.get(
            f"{BASE_URL}/v0/icd10",
            params={"value": dx["code"]},
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        body = r.json()
        return {"dx": dx, "valid": body.get("valid"), "found": body.get("found"), "title": body.get("title")}

    results = await asyncio.gather(*(check(dx) for dx in claim["diagnoses"]))

    errors = [
        f"{r['dx']['code']}: {'invalid format' if not r['valid'] else 'not in dictionary'}"
        for r in results if not r["valid"] or not r["found"]
    ]

    return {"accepted": not errors, "errors": errors, "annotated": results}

7. cURL example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/icd10?value=J45.0"

Validate an ICD-10-CM code with extension characters:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/icd10?value=S06.0X1A"

List child codes of a category:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/icd10/children?code=J45"

8. Understanding the response

Known code:

{
  "valid": true,
  "found": true,
  "icd10": "J45.0",
  "title": "Predominantly allergic asthma",
  "chapter": "J",
  "parent": "J45",
  "isLeaf": true,
  "source": "CMS",
  "version": "NLM-2026"
}

Valid format but unknown code:

{
  "valid": true,
  "found": false,
  "icd10": "J99.9",
  "title": null,
  "chapter": "J",
  "parent": null,
  "isLeaf": null,
  "source": null,
  "version": null
}

Invalid format:

{
  "valid": false
}

9. Edge cases

Python integration notes

In typed Python projects, model a validated ICD-10 code as a NewType — Icd10 = NewType("Icd10", str) — so type checkers enforce that only validated values flow through your claim pipeline. Pydantic models can use a custom validator that calls the IsValid API for the diagnosis_code field.

For Django or FastAPI services accepting diagnosis codes as request parameters, add a dependency/middleware that validates before the view runs. FastAPI's Depends() is a clean fit — a single dependency returns the full parsed API response, and every route that needs the metadata can declare it.

For claim scrubbers processing many codes, use httpx.AsyncClient with asyncio.gather() to validate all diagnoses on a claim concurrently. Cache responses in Redis keyed by the normalised code — a one-day TTL is safe; the dictionary changes annually.

• Read os.environ["ISVALID_API_KEY"] at startup and fail fast if missing
• Mock the client in unit tests with responses or respx — never call the real API in CI
• Log responses at DEBUG level for data-quality post-mortems
• For extreme throughput, pre-filter obviously malformed codes with a local regex before making API calls