How to Look Up ICD-10 Codes Programmatically with Node.js

ICD-10-CM codes are the standard classification system for medical diagnoses in the United States. Every claim submitted to a payer, every clinical decision support alert, and every public health report relies on these codes. If you are building an EHR, a billing system, a clinical trial platform, or any software that touches healthcare data, you will need to look up, search, and validate ICD-10 codes.

This article covers what ICD-10 codes are, how they are structured, and how to integrate code lookup into your application using JavaScript.

What ICD-10-CM codes look like

ICD-10-CM (Clinical Modification) codes follow a specific structure:

• 3-7 characters long
• First character: always a letter (A-Z, excluding U)
• Second and third characters: digits
• Characters 4-7: alphanumeric, separated from the first three by a decimal point

For example, E11.9 breaks down as:

• E = Endocrine, nutritional, and metabolic diseases (chapter)
• 11 = Type 2 diabetes mellitus (category)
• .9 = Without complications (specificity)

The 2025 code set from CMS contains 74,260 valid codes across 22 chapters. Codes are updated annually every October, with additions, deletions, and revisions.

Searching for codes by keyword

Suppose you are building a diagnosis search field in a clinical application. A provider types "diabetes" and expects to see relevant codes. Here is how to query the API:

curl "https://icd10-api-production.up.railway.app/search?q=diabetes&limit=5"

{
  "query": "diabetes",
  "total": 483,
  "results": [
    { "code": "E11.9", "description": "Type 2 diabetes mellitus without complications" },
    { "code": "E10.9", "description": "Type 1 diabetes mellitus without complications" },
    { "code": "E11.65", "description": "Type 2 diabetes mellitus with hyperglycemia" },
    { "code": "E13.9", "description": "Other specified diabetes mellitus without complications" },
    { "code": "O24.919", "description": "Unspecified diabetes mellitus in pregnancy, unspecified trimester" }
  ]
}

The search matches against both the code and the description text, so providers can search by clinical term ("chest pain"), anatomical location ("lumbar"), or code prefix ("E11").

Looking up a specific code

When you already have a code and need its description:

curl "https://icd10-api-production.up.railway.app/lookup/E11.9"

{
  "code": "E11.9",
  "description": "Type 2 diabetes mellitus without complications",
  "category": "E11",
  "categoryDescription": "Type 2 diabetes mellitus",
  "chapter": 4,
  "chapterDescription": "Endocrine, nutritional and metabolic diseases (E00-E89)",
  "valid": true
}

Integrating into a Node.js application

Here is a practical example: a diagnosis search component backend that returns formatted results for a clinical UI.

const ICD10_BASE = 'https://icd10-api-production.up.railway.app';

const searchDiagnoses = async (query, limit = 10) => {
  const params = new URLSearchParams({ q: query, limit: String(limit) });
  const res = await fetch(`${ICD10_BASE}/search?${params}`);
  const data = await res.json();

  return data.results.map((r) => ({
    code: r.code,
    display: `${r.code} - ${r.description}`,
    description: r.description,
  }));
};

const validateCode = async (code) => {
  const res = await fetch(`${ICD10_BASE}/validate/${code}`);
  const data = await res.json();
  return data.valid;
};

// Usage in a claim submission workflow
const diagnosisCode = 'E11.9';
const isValid = await validateCode(diagnosisCode);

if (!isValid) {
  throw new Error(`Invalid ICD-10 code: ${diagnosisCode}`);
}

// Search example for a typeahead field
const results = await searchDiagnoses('chest pain');
console.log(results);
// [
//   { code: "R07.9", display: "R07.9 - Chest pain, unspecified", ... },
//   { code: "R07.1", display: "R07.1 - Chest pain on breathing", ... },
//   ...
// ]

Using the MCP server in Claude Desktop

For developers and clinical informaticists who want to look up codes conversationally, the MCP Healthcare server bundles ICD-10 lookup alongside NPI, NDC, and DEA tools.

Install it with a single command:

npx @easysolutions906/mcp-healthcare

Add this to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "healthcare": {
      "command": "npx",
      "args": ["-y", "@easysolutions906/mcp-healthcare"]
    }
  }
}

Once connected, you can ask Claude things like "What is the ICD-10 code for type 2 diabetes with diabetic retinopathy?" and it will call the icd10_search tool, returning matching codes with their full hierarchy. You can also ask "Is E11.65 a valid ICD-10 code?" and get instant validation.

This is particularly useful during development when you need to verify test data, explore code hierarchies, or find the right code for a clinical scenario without leaving your editor.

Why not just use the CMS files directly?

CMS publishes ICD-10-CM as flat text files and XML. You could parse these yourself, but there are practical reasons to use an API instead:

• The raw files are not search-friendly. They are organized by code, not by clinical concept. Searching for "diabetes" requires scanning 74,260 entries.
• Validation requires the full code set. A code like E11.9 is valid, but E11.99 is not. You need the complete set loaded to validate.
• Annual updates. Every October, codes are added, revised, and deleted. The API dataset is rebuilt from the latest CMS release so you do not have to manage that lifecycle.

The dataset powering this API is built directly from the CMS 2025 ICD-10-CM release. A /data-info endpoint returns the build date and record count so you can verify freshness.

Get started

• REST API: Deployed on Railway. Search, lookup, and validate endpoints are open with no key required.
• MCP server: npx @easysolutions906/mcp-healthcare adds ICD-10 tools (plus NPI, NDC, and DEA) to Claude Desktop or Cursor.
• npm package: npm install @easysolutions906/mcp-healthcare

The full 2025 code set, searchable in milliseconds, with no signup and no rate limits on the free tier.