ICD-10 Validation in Node.js — 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 — infectious diseases, neoplasms, circulatory system, injuries, external causes, and so on. Each chapter is subdivided into blocks, categories, and highly specific sub-categories, forming a hierarchical tree of around 14,000 categories in the WHO base classification and over 70,000 billable codes in the US clinical modification.

ICD-10 codes appear throughout healthcare data: electronic health records (EHRs), HL7 messages, FHIR Condition resources, insurance claims (CMS-1500, UB-04), cancer registries, public health surveillance feeds, 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 always a letter (A–Z, excluding U which is reserved by WHO for provisional use). The next two characters are digits forming the category (e.g. J45 = Asthma). An optional decimal point followed by one to four additional characters specifies sub-categories and clinical detail.

The chapter letter maps to broad classes of disease:

A few well-known codes:

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

A common source of confusion: there is not one ICD-10 dataset but several national clinical modifications. The two most commonly encountered are:

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). It returns the diagnosis title, chapter, parent code, and leaf/billable flag.

Full parameter reference and response schema: ICD-10 Validation API docs →

6. Node.js code example

Validate a single ICD-10 code:

import { createClient } from '@isvalid-dev/sdk';

const iv = createClient({ apiKey: process.env.ISVALID_API_KEY });

// ── Validate an ICD-10 code ─────────────────────────────────────────────────

const result = await iv.icd10('J45.0');

if (!result.found) {
  console.log('Code is not in the ICD-10-CM dictionary');
} else {
  console.log('Title:', result.title);     // → 'Predominantly allergic asthma'
  console.log('Chapter:', result.chapter); // → 'J'
  console.log('Parent:', result.parent);   // → 'J45'
  console.log('Leaf:', result.isLeaf);     // → true (billable)
}

Expand a parent code into its children:

// Get all sub-categories of asthma (J45)
async function listChildren(parent) {
  const response = await fetch(
    `${BASE_URL}/v0/icd10/children?code=${encodeURIComponent(parent)}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } },
  );
  return response.json();
}

const children = await listChildren('J45');

for (const c of children) {
  console.log(`  ${c.icd10} — ${c.title}`);
}
// → J45.0 Predominantly allergic asthma
// → J45.1 Nonallergic asthma
// → J45.2 Mild intermittent asthma
// ...

// Validate every diagnosis on a claim before submission
async function scrubClaim(claim) {
  const results = await Promise.all(
    claim.diagnoses.map(async (dx) => {
      const r = await validateIcd10(dx.code);
      return { dx, valid: r.valid, found: r.found, title: r.title };
    }),
  );

  const errors = results
    .filter((r) => !r.valid || !r.found)
    .map((r) => `${r.dx.code}: ${!r.valid ? 'invalid format' : 'not in dictionary'}`);

  return { accepted: errors.length === 0, 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

Node.js integration notes

In a TypeScript project, model a validated ICD-10 code as a branded type — type Icd10 = string & { readonly __brand: 'Icd10' } — so the compiler enforces that only checked values flow through your claim pipeline. The IsValid SDK ships with full TypeScript definitions, giving you autocomplete on every response field without manual type declarations.

For Express.js or Fastify services that accept diagnosis codes as query or path parameters, add a middleware that validates the value before the route handler runs. On success, attach the full response to req.validatedData so handlers can use title, chapter, and isLeaf without a second API call.

For claim scrubbers processing thousands of codes per second, cache API responses in Redis keyed by the normalised code. A one-day TTL is safe; the dictionary changes at most annually. Use Promise.allSettled() to validate all diagnoses on a claim in parallel and collect all errors at once rather than failing on the first bad code.