ICD-11 Validation in Python — WHO MMS Diagnosis Codes

1. What is ICD-11?

ICD-11 is the 11th revision of the International Classification of Diseases, adopted by the World Health Assembly in 2019 and in official use since 1 January 2022. ICD-11 is a digital-native classification — a web-based ontology (the Foundation Component) from which multiple linearizations are derived.

The primary linearization is MMS — Mortality and Morbidity Statistics — which serves the role that ICD-10 filled: a flat list of stem codes for reporting, billing, and statistical analysis. MMS has about 17,000 categories across 28 chapters, with new chapters for traditional medicine and extension codes.

Adoption is gradual — as of 2026, most member states are still in the transition period. Many jurisdictions have set target dates between 2025 and 2030 for full ICD-11 implementation; systems commonly produce both ICD-10 and ICD-11 codes in parallel during the migration.

2. MMS stem code structure

An ICD-11 MMS stem code looks like this:

The first character is a digit 1–9 identifying the chapter (or V / X for supplementary and extension chapters). Subsequent characters are alphanumeric, with letters I and O excluded to prevent confusion with digits. An optional decimal + one or two characters specifies sub-categories.

3. ICD-10 vs ICD-11

4. Why ICD-11 validation matters

5. The right solution

The IsValid ICD-11 API validates format with a strict regex and performs dictionary lookup against a locally-maintained mirror of the current WHO ICD-11 MMS linearization (refreshed monthly from the WHO ICD-API).

Full parameter reference: ICD-11 Validation API docs →

6. Python code example

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

# icd11_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-11 MMS code ─────────────────────────────────────────────

result = iv.icd11("1A00")

if not result["found"]:
    print("Code is not in the WHO ICD-11 MMS dictionary")
else:
    print(f"Title: {result['title']}")                   # → 'Cholera'
    print(f"Chapter: {result['chapter']}")               # → '01'
    print(f"Foundation URI: {result['foundationUri']}")   # → WHO foundation link
    print(f"Version: {result['version']}")

# ICD-10 starts with a LETTER, ICD-11 starts with a DIGIT.
# Delegate validation to the right endpoint.

def validate_diagnosis(code: str) -> dict:
    first = code.strip()[:1]
    if first.isdigit():
        return {"revision": "ICD-11", **validate_icd11(code)}
    return {"revision": "ICD-10", **validate_icd10(code)}


print(validate_diagnosis("J45.0"))  # → ICD-10
print(validate_diagnosis("CA23"))   # → ICD-11

7. cURL example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/icd11?value=1A00"

Validate a circulatory code:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/icd11?value=BA00"

8. Understanding the response

Known code:

{
  "valid": true,
  "found": true,
  "icd11": "1A00",
  "title": "Cholera",
  "chapter": "01",
  "parent": null,
  "isLeaf": false,
  "foundationUri": "http://id.who.int/icd/entity/257068234",
  "blockId": null,
  "version": "ICD-11 for Mortality and Morbidity Statistics"
}

Valid format but unknown code:

{
  "valid": true,
  "found": false,
  "icd11": "9ZZ9",
  "title": null,
  "chapter": null,
  "parent": null,
  "isLeaf": null,
  "foundationUri": null,
  "blockId": null,
  "version": null
}

Invalid format:

{
  "valid": false
}

9. Edge cases

expression = "CA23.3&XB25"
parts = expression.split("&")

results = [validate_icd11(p) for p in parts]
all_valid = all(r["valid"] and r["found"] for r in results)

Python integration notes

In typed Python projects, model ICD-10 and ICD-11 as distinct NewType aliases so type checkers prevent accidental cross-revision comparison. A Pydantic Union[Icd10, Icd11] discriminated by the first character is useful when storing mixed data during migration periods.

Because the first character unambiguously distinguishes the two revisions, a cheap local dispatch check can route codes to the right endpoint without an extra network call: code[0].isdigit() → ICD-11, otherwise ICD-10.

Use httpx.AsyncClient for concurrent validation of batches and cache responses in Redis keyed by normalised code. A one-day TTL is appropriate — WHO publishes annual releases, so the dictionary is effectively static within a year.

• Read os.environ["ISVALID_API_KEY"] at startup and fail fast if missing
• Use respx to mock the IsValid client in unit tests — never call the real API in CI
• For FastAPI services, expose ICD validation as a dependency so every endpoint automatically benefits from the pre-validated metadata
• Record version in your audit log so you can prove which MMS release validated each historical record