# NPI Registry Provider Scraper (`automation-lab/npi-registry-provider-scraper`) Actor Search the public CMS NPI Registry and export provider contact details, specialties, taxonomy codes, addresses, credentials, and NPI metadata. - **URL**: https://apify.com/automation-lab/npi-registry-provider-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Lead generation - **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 ## NPI Registry Provider Scraper Search the public CMS NPI Registry and export provider records with contact details, taxonomy/specialty data, addresses, credentials, and source metadata. Use this actor when you need a clean provider list for healthcare operations, credentialing, lead enrichment, market mapping, or compliance research. ### What does NPI Registry Provider Scraper do? - ๐Ÿ”Ž Searches the CMS NPI Registry public API. - ๐Ÿฅ Exports one dataset row per provider record. - ๐Ÿ“ Includes mailing and practice-location address fields. - โ˜Ž๏ธ Captures phone and fax values when the registry provides them. - ๐Ÿงพ Includes taxonomies, primary license, status, and dates. - ๐Ÿง‘โ€โš•๏ธ Handles individual providers and organizations. - ๐Ÿงฉ Supports batch searches and exact NPI lookups. ### Who is it for? - Healthcare operations teams building provider directories. - Credentialing teams checking NPI status and specialty data. - Sales and marketing teams researching healthcare provider leads. - Data enrichment teams matching provider CRM records. - Recruiters mapping physicians, clinics, facilities, and specialties. - Analysts studying provider density by city, state, ZIP, or taxonomy. ### Why use this actor? The CMS NPI Registry is public, but raw API output is nested and inconvenient for spreadsheet workflows. This actor turns registry responses into flat, export-friendly rows while preserving nested details as JSON fields. It also handles pagination, batching, deduplication, and metadata so your team can focus on analysis. ### How much does it cost to scrape NPI Registry providers? This actor uses pay-per-event pricing. There is a small start charge per run and a per-provider charge for each saved NPI record. Use a low `maxResults` value for first tests, then increase it for production exports. Final tiered pricing is validated during cloud cost testing before publication. ### Input options - `mode`: choose `search` or `lookup`. - `maxResults`: total provider records to save. - `searches`: optional batch of search filter objects. - `npiNumbers`: exact NPI values for lookup mode. - `firstName` and `lastName`: individual provider filters. - `organizationName`: facility, clinic, practice, or company name. - `taxonomyDescription`: specialty text such as Cardiology or Dentist. - `city`, `state`, `postalCode`, `countryCode`: location filters. - `enumerationType`: individual providers (`NPI-1`) or organizations (`NPI-2`). - `useFirstNameAlias`: include common first-name aliases supported by CMS. ### Example search input ```json { "mode": "search", "maxResults": 50, "state": "MA", "city": "Boston", "taxonomyDescription": "Cardiology" } ```` ### Example batch input ```json { "mode": "search", "maxResults": 100, "searches": [ { "state": "MA", "city": "Boston", "taxonomyDescription": "Cardiology" }, { "state": "NY", "city": "New York", "taxonomyDescription": "Family Medicine" } ] } ``` ### Example lookup input ```json { "mode": "lookup", "maxResults": 10, "npiNumbers": ["1730958521"] } ``` ### Output data The dataset contains provider identity, contact, taxonomy, and metadata fields. | Field | Description | | --- | --- | | `npi` | National Provider Identifier. | | `providerName` | Individual or organization display name. | | `providerType` | Individual, organization, or unknown. | | `status` | Registry status value. | | `locationPhone` | Practice-location phone when available. | | `primaryTaxonomyDescription` | Main specialty description. | | `primaryTaxonomyCode` | Main taxonomy code. | | `primaryLicenseNumber` | License attached to primary taxonomy. | | `taxonomyDescriptions` | Semicolon-separated specialty descriptions. | | `identifiersJson` | Additional identifiers as JSON. | | `endpointsJson` | Registry endpoint data as JSON. | | `practiceLocationsJson` | Additional practice locations as JSON. | | `sourceApiUrl` | Exact CMS API URL used. | | `fetchedAt` | Actor fetch timestamp. | ### Output example ```json { "npi": "1730958521", "providerName": "SARAH MARGARET BEARGIE PharmD", "providerType": "individual", "locationCity": "BOSTON", "locationState": "MA", "locationPhone": "617-724-1939", "primaryTaxonomyDescription": "Pharmacist" } ``` ### Tips for best results - Start with a city, state, and specialty to keep searches targeted. - Use `enumerationType` when you only want individuals or organizations. - Use batch searches for territory lists or specialty lists. - Keep the first run small to inspect output columns. - Increase `maxResults` after you confirm the search filters are correct. - Use exact `npiNumbers` for enrichment or verification workflows. ### Pagination and limits The actor requests pages from the CMS API and stops when it reaches `maxResults` or no more records are returned. The CMS API has practical pagination limits, so very broad searches should be split by city, state, specialty, or ZIP code. Targeted searches produce cleaner and more useful provider lists. ### Integrations - Export to CSV for spreadsheet review. - Send records to a CRM enrichment pipeline. - Join by `npi` with internal provider records. - Use `taxonomyCodes` to segment specialties. - Use `locationState` and `locationPostalCode` for territory mapping. - Use `sourceApiUrl` as an audit trail for compliance review. ### 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/npi-registry-provider-scraper').call({ mode: 'search', maxResults: 50, state: 'MA', city: 'Boston', taxonomyDescription: 'Cardiology' }); console.log(run.defaultDatasetId); ``` ### API usage with Python ```python from apify_client import ApifyClient client = ApifyClient() run = client.actor('automation-lab/npi-registry-provider-scraper').call(run_input={ 'mode': 'search', 'maxResults': 50, 'state': 'MA', 'city': 'Boston', 'taxonomyDescription': 'Cardiology', }) print(run['defaultDatasetId']) ``` ### API usage with cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/automation-lab~npi-registry-provider-scraper/runs?token=$APIFY_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"mode":"search","maxResults":50,"state":"MA","city":"Boston","taxonomyDescription":"Cardiology"}' ``` ### MCP usage Connect this actor through Apify MCP at: ```text https://mcp.apify.com/?tools=automation-lab/npi-registry-provider-scraper ``` Claude Code setup: ```bash claude mcp add apify-npi-registry https://mcp.apify.com/?tools=automation-lab/npi-registry-provider-scraper ``` Claude Desktop JSON configuration: ```json { "mcpServers": { "apify-npi-registry": { "url": "https://mcp.apify.com/?tools=automation-lab/npi-registry-provider-scraper" } } } ``` Example prompts: - "Find cardiology providers in Boston and summarize specialties." - "Look up these NPI numbers and return phone and address fields." - "Build a provider list for physical therapists in Austin, Texas." ### Data quality notes The actor returns data exactly as published by the CMS NPI Registry. Some providers omit phone, fax, endpoint, or license fields. Address and taxonomy values can reflect registry updates submitted by providers or organizations. Always verify critical business decisions against the official source. ### Legality This actor uses the public CMS NPI Registry API. The NPI Registry is intended for public provider lookup, but users remain responsible for following applicable laws, platform terms, privacy rules, and healthcare compliance requirements. Do not use exported data for spam or unlawful targeting. ### FAQ #### Is this an official CMS tool? No. This is an independent Apify actor that reads the public CMS NPI Registry API and formats results for exports and automations. #### Can I search multiple provider specialties? Yes. Add multiple objects to `searches`, one per specialty, city, state, organization, or other filter combination. ### Troubleshooting #### Why did I get fewer records than expected? The CMS API may have fewer matching providers for your exact filters. Try broader specialty text, remove city, or split by state and ZIP code. #### Why are phone numbers missing? Phone and fax fields are optional in registry records. The actor saves them when the CMS response includes them. #### Why does a broad state search stop early? Very broad queries can hit API pagination limits. Split the workload by city, ZIP prefix, specialty, or organization name for better coverage. ### Related scrapers - https://apify.com/automation-lab/google-maps-lead-finder - https://apify.com/automation-lab/yelp-scraper - https://apify.com/automation-lab/doctoralia-mexico-scraper - https://apify.com/automation-lab/apple-maps-places-scraper ### Changelog - Initial version: CMS NPI Registry search and exact NPI lookup. ### Support If a run fails, include the run URL, input JSON, and a short description of the expected providers. ### Quick reference - Use `mode: search` for discovery. - Use `mode: lookup` for exact NPI enrichment. - Use `maxResults` to control spend. - Use `searches` for batch territories. - Use `taxonomyDescription` for specialties. - Use `enumerationType: NPI-1` for individuals. - Use `enumerationType: NPI-2` for organizations. - Export JSON when you need nested taxonomy details. - Export CSV when you need spreadsheet-friendly leads. # Actor input Schema ## `mode` (type: `string`): Use search filters or look up exact NPI numbers. ## `maxResults` (type: `integer`): Maximum total provider records to save across all searches or NPI lookups. ## `searches` (type: `array`): Optional list of search objects. If empty, the top-level filters below are used as one search. ## `npiNumbers` (type: `array`): Exact NPI numbers to look up when mode is Lookup NPI numbers. ## `firstName` (type: `string`): Provider first name for individual NPI-1 records. Wildcards are supported by the CMS API. ## `lastName` (type: `string`): Provider last name for individual NPI-1 records. ## `organizationName` (type: `string`): Organization or facility name for NPI-2 records. ## `taxonomyDescription` (type: `string`): Specialty text such as Cardiology, Family Medicine, Dentist, or Physical Therapist. ## `enumerationType` (type: `string`): Filter to individuals (NPI-1) or organizations (NPI-2). ## `useFirstNameAlias` (type: `boolean`): Ask the NPI API to include common first-name aliases. ## `city` (type: `string`): Provider city. ## `state` (type: `string`): Two-letter US state code. ## `postalCode` (type: `string`): ZIP or postal code filter. ## `countryCode` (type: `string`): Two-letter country code used by the NPI Registry. ## Actor input object example ```json { "mode": "search", "maxResults": 20, "searches": [ { "state": "MA", "city": "Boston", "taxonomyDescription": "Cardiology" } ], "npiNumbers": [ "1730958521" ], "taxonomyDescription": "Cardiology", "enumerationType": "", "useFirstNameAlias": true, "city": "Boston", "state": "MA", "countryCode": "US" } ``` # 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 = { "searches": [ { "state": "MA", "city": "Boston", "taxonomyDescription": "Cardiology" } ], "npiNumbers": [ "1730958521" ], "taxonomyDescription": "Cardiology", "city": "Boston", "state": "MA" }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/npi-registry-provider-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 = { "searches": [{ "state": "MA", "city": "Boston", "taxonomyDescription": "Cardiology", }], "npiNumbers": ["1730958521"], "taxonomyDescription": "Cardiology", "city": "Boston", "state": "MA", } # Run the Actor and wait for it to finish run = client.actor("automation-lab/npi-registry-provider-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 '{ "searches": [ { "state": "MA", "city": "Boston", "taxonomyDescription": "Cardiology" } ], "npiNumbers": [ "1730958521" ], "taxonomyDescription": "Cardiology", "city": "Boston", "state": "MA" }' | apify call automation-lab/npi-registry-provider-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/npi-registry-provider-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "NPI Registry Provider Scraper", "description": "Search the public CMS NPI Registry and export provider contact details, specialties, taxonomy codes, addresses, credentials, and NPI metadata.", "version": "0.1", "x-build-id": "WEXF5QZbeMnxSkT4A" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~npi-registry-provider-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-npi-registry-provider-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~npi-registry-provider-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-npi-registry-provider-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~npi-registry-provider-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-npi-registry-provider-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": { "mode": { "title": "Mode", "enum": [ "search", "lookup" ], "type": "string", "description": "Use search filters or look up exact NPI numbers.", "default": "search" }, "maxResults": { "title": "Maximum provider records", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum total provider records to save across all searches or NPI lookups.", "default": 20 }, "searches": { "title": "Search filter batches", "type": "array", "description": "Optional list of search objects. If empty, the top-level filters below are used as one search." }, "npiNumbers": { "title": "NPI numbers", "type": "array", "description": "Exact NPI numbers to look up when mode is Lookup NPI numbers.", "items": { "type": "string" } }, "firstName": { "title": "First name", "type": "string", "description": "Provider first name for individual NPI-1 records. Wildcards are supported by the CMS API." }, "lastName": { "title": "Last name", "type": "string", "description": "Provider last name for individual NPI-1 records." }, "organizationName": { "title": "Organization name", "type": "string", "description": "Organization or facility name for NPI-2 records." }, "taxonomyDescription": { "title": "Specialty / taxonomy description", "type": "string", "description": "Specialty text such as Cardiology, Family Medicine, Dentist, or Physical Therapist." }, "enumerationType": { "title": "Enumeration type", "enum": [ "", "NPI-1", "NPI-2" ], "type": "string", "description": "Filter to individuals (NPI-1) or organizations (NPI-2).", "default": "" }, "useFirstNameAlias": { "title": "Use first-name aliases", "type": "boolean", "description": "Ask the NPI API to include common first-name aliases.", "default": true }, "city": { "title": "City", "type": "string", "description": "Provider city." }, "state": { "title": "State", "type": "string", "description": "Two-letter US state code." }, "postalCode": { "title": "Postal code", "type": "string", "description": "ZIP or postal code filter." }, "countryCode": { "title": "Country code", "type": "string", "description": "Two-letter country code used by the NPI Registry.", "default": "US" } } }, "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 } } } } } } } } } } ```