# US Medicare Clinician & Clinic Territory Leads (`afkdigital/newapi05-us-medicare-clinician-clinic-leads`) Actor

Search official CMS Doctors & Clinicians public data by US state, specialty and city. Export clinician, practice, phone, telehealth and group-size signals for territory research. No appointment availability or insurance-network claims. Independent of CMS.

- **URL**: https://apify.com/afkdigital/newapi05-us-medicare-clinician-clinic-leads.md
- **Developed by:** [AFK Digital](https://apify.com/afkdigital) (community)
- **Categories:** Lead generation, Business
- **Stats:** 2 total users, 1 monthly users, 50.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$5.00 / 1,000 unique clinician and practice locations

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## US Medicare Clinician & Clinic Territory Leads (NEWAPI05)

Find U.S. Medicare clinicians and practice locations in the official CMS Doctors & Clinicians National Downloadable File through its public API. Search by two-letter state, CMS primary specialty and optional city. CARDIOLOGY is an alias for CARDIOVASCULAR DISEASE (CARDIOLOGY); other values must match CMS. Apply optional ZIP prefix, CMS telehealth indicator and reported organization member count filters to retrieved rows. Export the default Apify Dataset as JSON or CSV for Clay, n8n and other CRM workflows.

**Example:** `{"state":"NY","specialty":"DERMATOLOGY","city":"NEW YORK","maxResults":10}`.

The record is one unique **NPI plus practice location** within a run. CMS has multiple enrollment rows per clinician and site; duplicate rows are not charged. CMS fields may be missing or self-reported. The telehealth indicator is not an online-booking flag. Medicare assignment is not an insurance-network list. The source does not provide website, appointment slots, next available date, or patient load, so the Actor does not invent those fields. It never accesses patient records or books appointments.

Source: [CMS National Downloadable File](https://data.cms.gov/provider-data/dataset/mj5m-pzi6). [CMS explains use of government data](https://data.cms.gov/provider-data/topics/home-health-services/about-using-government-data); government works are public domain and permission is not required for reuse. CMS attribution is included in every row. Independent product; no CMS endorsement. NPI registration does not validate licensing or credentials.

The default run searches NY dermatology, stops at 10 unique records, and is designed to finish within five minutes. At most 20 pages of 100 source rows can be requested per run; default 3. A request has a 5-second connect and 15-second read timeout, up to three attempts with exponential backoff. ZIP, telehealth and size filters are applied after retrieval; if the page budget is reached, the `SUMMARY` record marks coverage as limited. The CMS dataset has publication lag and may include multiple sites; consult the source for its current release date.

**Pricing target:** Pay per event, `$0.005` for each `apify-default-dataset-item`, or **$5 per 1,000 unique clinician/practice-location items**. No charge for repeated source rows. No Actor-start fee is intended. Platform usage may vary with Apify's monetization setting and must be confirmed on the Store pricing panel. The code emits one dataset item per unit and does not manually charge another event.

### Local validation

`python -m pytest -q tests` and `APIFY_LOCAL_STORAGE_DIR=/tmp/newapi05-local python -m src.main` (install `requirements.txt` first). On Apify, set input and download the default Dataset using its JSON or CSV endpoint. The run's `SUMMARY` key-value record reports count, source count, scanned rows, page budget and coverage.

#### CMS source resilience

The Actor first queries the official CMS Provider Data Catalog API. If a
query fails after bounded retries (for example a transient 503), it resolves the
current official CSV distribution from the CMS metastore and streams that file.
It applies the same state, specialty, city, ZIP, telehealth, group-size, unique
NPI/location, maxResults, and maxPages limits. The CSV fallback reports
`source_method: official_csv_fallback`, the distribution URL, and the number of
file rows examined in the `SUMMARY` key-value record. Its
`source_match_count` is null when scanning stops early because the full CMS
match count is then unknown. If both official sources are unavailable or a
safety limit is reached, the run fails; it never labels an outage as no matches.

# Actor input Schema

## `state` (type: `string`):

Two-letter CMS code, for example NY or CA.

## `specialty` (type: `string`):

Exact CMS primary specialty, for example DERMATOLOGY. CARDIOLOGY maps to the CMS cardiovascular label.

## `city` (type: `string`):

Optional exact CMS city name, case insensitive.

## `zipPrefix` (type: `string`):

Optional first 3 to 5 ZIP digits. Applied to retrieved rows; request/page budget can limit coverage.

## `telehealthOnly` (type: `boolean`):

Include only records where CMS telehlth is Y. This does not mean online booking.

## `minGroupSize` (type: `integer`):

Optional CMS num_org_mem filter applied to retrieved rows.

## `maxResults` (type: `integer`):

Stop after this many unique NPI and practice location records.

## `maxPages` (type: `integer`):

Cost and coverage guard; each page contains at most 100 rows.

## Actor input object example

```json
{
  "state": "NY",
  "specialty": "DERMATOLOGY",
  "telehealthOnly": false,
  "maxResults": 10,
  "maxPages": 3
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("afkdigital/newapi05-us-medicare-clinician-clinic-leads").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("afkdigital/newapi05-us-medicare-clinician-clinic-leads").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call afkdigital/newapi05-us-medicare-clinician-clinic-leads --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,afkdigital/newapi05-us-medicare-clinician-clinic-leads"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/X3NgQOzAAxKFZGQcu/builds/qAJ3jl0ZyuJBx7WSd/openapi.json