# ICD-10-CM Codes Scraper (`automation-lab/icd-10-cm-codes-scraper`) Actor ๐Ÿฅ Export official CMS ICD-10-CM diagnosis code releases with descriptions, billable flags, hierarchy, addenda, and source audit URLs. - **URL**: https://apify.com/automation-lab/icd-10-cm-codes-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 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 ```json { "releaseYear": "2026", "updateType": "annual", "includeAddenda": true, "includeHierarchy": true, "maxItems": 1000 } ```` ### Example output ```json { "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 ```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 ```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 ```bash 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: ```bash claude mcp add apify-icd10 --url "https://mcp.apify.com/?tools=automation-lab/icd-10-cm-codes-scraper" ``` Claude Desktop JSON config block: ```json { "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: ```bash 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: ```json { "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. # Actor input Schema ## `releaseYear` (type: `string`): CMS ICD-10-CM release year to download. Use latest for the newest code descriptions ZIP discovered on cms.gov. ## `updateType` (type: `string`): Choose annual October releases, April updates, or auto to use the newest matching release for the selected year. ## `includeAddenda` (type: `boolean`): Also emit Add/Delete/Revise rows from CMS addenda files when present in the ZIP. ## `includeHierarchy` (type: `boolean`): Add chapter, chapter range, and nearest parent code fields when they can be derived from the official order file. ## `maxItems` (type: `integer`): Limit dataset rows for testing or partial exports. Increase to 100000 for a full release export. ## Actor input object example ```json { "releaseYear": "latest", "updateType": "auto", "includeAddenda": true, "includeHierarchy": true, "maxItems": 20 } ``` # Actor output Schema ## `overview` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "releaseYear": "latest", "updateType": "auto", "includeAddenda": true, "includeHierarchy": true, "maxItems": 20 }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/icd-10-cm-codes-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "releaseYear": "latest", "updateType": "auto", "includeAddenda": True, "includeHierarchy": True, "maxItems": 20, } # Run the Actor and wait for it to finish run = client.actor("automation-lab/icd-10-cm-codes-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "releaseYear": "latest", "updateType": "auto", "includeAddenda": true, "includeHierarchy": true, "maxItems": 20 }' | apify call automation-lab/icd-10-cm-codes-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/icd-10-cm-codes-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "ICD-10-CM Codes Scraper", "description": "๐Ÿฅ Export official CMS ICD-10-CM diagnosis code releases with descriptions, billable flags, hierarchy, addenda, and source audit URLs.", "version": "0.1", "x-build-id": "gDYAcgzsXl6w4TVqy" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~icd-10-cm-codes-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-icd-10-cm-codes-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/automation-lab~icd-10-cm-codes-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-icd-10-cm-codes-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/automation-lab~icd-10-cm-codes-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-icd-10-cm-codes-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "releaseYear": { "title": "Release year", "type": "string", "description": "CMS ICD-10-CM release year to download. Use latest for the newest code descriptions ZIP discovered on cms.gov.", "default": "latest" }, "updateType": { "title": "Update type", "enum": [ "auto", "annual", "april" ], "type": "string", "description": "Choose annual October releases, April updates, or auto to use the newest matching release for the selected year.", "default": "auto" }, "includeAddenda": { "title": "Include addenda/change rows", "type": "boolean", "description": "Also emit Add/Delete/Revise rows from CMS addenda files when present in the ZIP.", "default": true }, "includeHierarchy": { "title": "Include hierarchy fields", "type": "boolean", "description": "Add chapter, chapter range, and nearest parent code fields when they can be derived from the official order file.", "default": true }, "maxItems": { "title": "Maximum records", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Limit dataset rows for testing or partial exports. Increase to 100000 for a full release export.", "default": 20 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```