ICD-10-CM Codes Scraper

Download official CMS ICD-10-CM diagnosis code releases as clean, normalized Apify datasets. The actor discovers CMS release ZIP files, parses the official order/code description text files, and outputs code rows with descriptions, billable flags, hierarchy metadata, release year, effective date, and source-file audit links.

What does ICD-10-CM Codes Scraper do?

ICD-10-CM Codes Scraper turns CMS release files into ready-to-use JSON, CSV, Excel, Parquet, or API data.

• 🏥 Finds official ICD-10-CM code description ZIP files on cms.gov
• 📦 Downloads the selected release archive
• 🧾 Parses CMS order files and code description files
• ✅ Marks codes as billable or non-billable when CMS provides the flag
• 🧭 Adds chapter, chapter range, and parent-code metadata
• 🔁 Optionally includes CMS addenda rows such as Add, Delete, and Revise
• 🔗 Preserves source ZIP URL, CMS page URL, and source file name for auditing

Who is it for?

This actor is designed for teams that need versioned healthcare terminology data rather than a one-code lookup.

• Revenue-cycle vendors building claims validation workflows
• EHR and health-data platforms refreshing diagnosis terminology
• Medical billing teams checking official CMS release files
• Compliance analysts monitoring ICD-10-CM updates
• Healthcare data engineers loading code tables into warehouses
• Terminology products and search tools enriching code descriptions
• Consultants comparing annual and April code updates

Why use this actor?

CMS publishes ICD-10-CM data in release ZIP files. Those files are authoritative, but they are not immediately convenient for automation pipelines. This actor gives you a repeatable API-driven extraction step, so your team can refresh code tables without manual downloads, unzip steps, and fixed-width parsing scripts.

Official source

The source page is the CMS ICD-10 code files page:

https://www.cms.gov/medicare/coding-billing/icd-10-codes

The actor does not use unofficial mirrors. Every output row contains sourceFileUrl, sourceFileName, and sourcePageUrl so downstream systems can trace where the row came from.

Data you can extract

Field	Description
recordType	code for normal code rows or addendum for change rows
code	Raw CMS code without a decimal
formattedCode	ICD-10-CM style code with a decimal when applicable
description	Primary output description
shortDescription	CMS short label when available
longDescription	CMS long label when available
billable	true, false, or null when not available
releaseYear	CMS release year
updateType	annual, april, or unknown
effectiveDate	Derived release effective date
sequence	CMS order-file sequence number
chapter	Derived ICD-10-CM chapter
chapterRange	Code range for the derived chapter
parentCode	Nearest parent code found in the release
changeAction	Add/Delete/Revise for addenda rows
sourceFileName	Text file parsed inside the ZIP
sourceFileUrl	CMS ZIP URL
sourcePageUrl	CMS source page
scrapedAt	Extraction timestamp

How much does it cost to extract ICD-10-CM codes?

This actor uses pay-per-event pricing. There is a small run-start event and one item event for each ICD-10-CM code or addendum row produced. You can limit test runs with maxItems and increase it for full release exports.

Input options

releaseYear

Use latest to let the actor pick the newest CMS ICD-10-CM code description ZIP. You can also specify a year such as 2026 or 2025.

updateType

Choose auto, annual, or april.

• auto chooses the newest matching source for the selected year.
• annual targets annual October release files.
• april targets April update files when CMS publishes them.

includeAddenda

When enabled, the actor emits Add/Delete/Revise rows from addenda files in the selected ZIP.

includeHierarchy

When enabled, the actor derives chapter fields and a nearest parent code from the order file.

maxItems

Use this as a safety limit. A small value is useful for testing; a high value exports the full release.

Example input

{
  "releaseYear": "2026",
  "updateType": "annual",
  "includeAddenda": true,
  "includeHierarchy": true,
  "maxItems": 1000
}

Example output

{
  "recordType": "code",
  "code": "A000",
  "formattedCode": "A00.0",
  "description": "Cholera due to Vibrio cholerae 01, biovar cholerae",
  "shortDescription": "Cholera due to Vibrio cholerae 01, biovar cholerae",
  "longDescription": "Cholera due to Vibrio cholerae 01, biovar cholerae",
  "billable": true,
  "releaseYear": 2026,
  "updateType": "annual",
  "effectiveDate": "2025-10-01",
  "sequence": 2,
  "chapter": "Chapter 1: Certain infectious and parasitic diseases",
  "chapterRange": "A00-B99",
  "parentCode": "A00",
  "changeAction": null,
  "sourceFileName": "icd10cm_order_2026.txt",
  "sourceFileUrl": "https://www.cms.gov/files/zip/2026-code-descriptions-tabular-order.zip",
  "sourcePageUrl": "https://www.cms.gov/medicare/coding-billing/icd-10-codes",
  "scrapedAt": "2026-07-03T00:00:00.000Z"
}

How to run the actor

1. Open the actor on Apify.
2. Pick a release year or keep latest.
3. Choose auto, annual, or april.
4. Keep includeHierarchy enabled for richer data.
5. Set maxItems low for a test run or high for a full export.
6. Start the run.
7. Download the dataset or call the dataset API.

Tips for best results

• Use maxItems: 100 for a quick validation run.
• Use maxItems: 100000 when you want the complete release.
• Use a fixed releaseYear for reproducible data pipelines.
• Keep source URL fields when loading records into a warehouse.
• Use recordType and changeAction to separate normal code rows from addenda rows.

Common workflows

Claims validation enrichment

Load the output into your claims or revenue-cycle database and join by code or formattedCode.

Release monitoring

Run the actor on latest periodically and compare rows by releaseYear, sourceFileName, and changeAction.

EHR terminology refresh

Use the dataset API to feed ICD-10-CM descriptions and billable flags into an internal terminology service.

Compliance audit trail

Store sourceFileUrl, sourceFileName, and scrapedAt so analysts can verify the exact CMS source used.

API usage with Node.js

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/icd-10-cm-codes-scraper').call({
  releaseYear: '2026',
  updateType: 'annual',
  includeAddenda: true,
  includeHierarchy: true,
  maxItems: 1000,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0]);

API usage with Python

from apify_client import ApifyClient
import os

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/icd-10-cm-codes-scraper').call(run_input={
    'releaseYear': '2026',
    'updateType': 'annual',
    'includeAddenda': True,
    'includeHierarchy': True,
    'maxItems': 1000,
})

items = client.dataset(run['defaultDatasetId']).list_items().items
print(items[0])

API usage with cURL

curl -X POST "https://api.apify.com/v2/acts/automation-lab~icd-10-cm-codes-scraper/runs?token=$APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"releaseYear":"2026","updateType":"annual","includeAddenda":true,"includeHierarchy":true,"maxItems":1000}'

MCP integration

Use this actor through Apify MCP when you want Claude or another MCP client to refresh ICD-10-CM data.

MCP server URL:

https://mcp.apify.com/?tools=automation-lab/icd-10-cm-codes-scraper

Claude Code CLI add command:

$claude mcp add apify-icd10 --url "https://mcp.apify.com/?tools=automation-lab/icd-10-cm-codes-scraper"

Claude Desktop JSON config block:

{
  "mcpServers": {
    "apify-icd10": {
      "url": "https://mcp.apify.com/?tools=automation-lab/icd-10-cm-codes-scraper"
    }
  }
}

Example prompts showing MCP usage:

• "Run the ICD-10-CM Codes Scraper for the latest CMS release and return 20 rows."
• "Use the ICD-10-CM scraper to export 2026 annual codes and summarize billable counts."

Claude Code MCP example

Add this actor to Claude Code with:

$claude mcp add apify-icd10 --url "https://mcp.apify.com/?tools=automation-lab/icd-10-cm-codes-scraper"

Then ask Claude Code:

Run the ICD-10-CM Codes Scraper for the 2026 annual CMS release and summarize how many billable versus non-billable rows were returned.

Claude Desktop MCP example

Add this MCP server configuration to Claude Desktop:

{
  "mcpServers": {
    "apify-icd10": {
      "url": "https://mcp.apify.com/?tools=automation-lab/icd-10-cm-codes-scraper"
    }
  }
}

Example prompts:

Export the latest ICD-10-CM release and show me the first 20 code rows with descriptions and parent codes.

Compare the latest ICD-10-CM addenda rows and list all Add/Delete/Revise actions in the dataset.

Integrations

• Send dataset exports to Snowflake, BigQuery, or Postgres.
• Feed output into billing rules engines.
• Compare addenda rows in a scheduled workflow.
• Enrich claim diagnosis codes in internal APIs.
• Trigger alerts when a new CMS source ZIP appears.

Related scrapers

Useful automation-lab actors for adjacent healthcare, data, and compliance workflows:

• https://apify.com/automation-lab/website-contact-finder
• https://apify.com/automation-lab/csv-to-json-converter
• https://apify.com/automation-lab/jsonld-validator
• https://apify.com/automation-lab/structured-data-extractor

Data freshness

The actor discovers links from the live CMS ICD-10 page at runtime. If CMS adds a new annual or April code description ZIP, releaseYear: latest can pick it up without changing your input.

Limitations

• The actor parses ICD-10-CM diagnosis code description/order files, not ICD-10-PCS procedure code tables.
• Chapter fields are derived from standard ICD-10-CM ranges.
• CMS file naming can change; source URL fields make such changes visible in output.
• Medical coding decisions should be reviewed by qualified professionals.

Troubleshooting

Why did I get fewer rows than expected?

Check maxItems. The actor stops when it reaches that limit, even if the CMS release contains more rows.

Why did a year fail?

CMS may not publish the requested year/update combination on the current source page. Try releaseYear: latest or a year visible on cms.gov.

Why are addenda rows missing?

Some ZIP files do not contain addenda text files, or includeAddenda may be disabled.

Legality

The actor downloads public CMS files. You are responsible for using the data according to CMS terms, applicable healthcare regulations, and your organization's compliance requirements.

Is it legal to scrape ICD-10-CM codes?

CMS publishes these files publicly for healthcare coding use. The actor automates access to those public release files, but your team remains responsible for compliance review.

FAQ

Does this actor require a proxy?

No. CMS files are public and the actor uses direct HTTP downloads.

Does it output billable flags?

Yes, when the CMS order file provides the 0/1 billable flag. Addenda rows can have null when no flag is present.

Can I export CSV?

Yes. Use Apify dataset export options to download CSV, Excel, JSON, JSONL, XML, RSS, or Parquet.

Can I run a full release export?

Yes. Set maxItems high enough, for example 100000.

Support

If CMS changes file names or ZIP structure and the actor cannot find a release, open an issue with the release year and update type you tried.

Changelog

• Initial version: CMS ICD-10-CM release discovery, ZIP parsing, normalized code rows, addenda rows, hierarchy metadata, and source audit fields.