# CMS PECOS Enrollment & Ordering Eligibility Lookup (`automation-lab/cms-pecos-medicare-enrollment-lookup`) Actor

Look up NPIs or exact names in official CMS Order and Referring records. Export membership, identity, eligibility flags and release date. Not listed does not mean unenrolled.

- **URL**: https://apify.com/automation-lab/cms-pecos-medicare-enrollment-lookup.md
- **Developed by:** [Automation Lab](https://apify.com/automation-lab) (community)
- **Categories:** Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.60 / 1,000 item extracteds

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/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

## CMS PECOS Enrollment & Ordering Eligibility Lookup

Check supplied NPIs or exact practitioner names against the official CMS Order and Referring dataset. This PECOS enrollment-related public extract supports recurring Medicare ordering and referring eligibility checks, not comprehensive enrollment determinations.

The Actor returns dataset membership, NPI and practitioner name, five eligibility flags, and the CMS release date. It uses no private PECOS account and submits no enrollment applications.

### Who is this for?

Billing teams, DME suppliers, home health operations, and credentialing analysts can check whether a practitioner appears in a particular CMS release before investigating ordering requirements.

### Why use this Actor?

- Resolve the current official CMS release automatically.
- Pin a dated snapshot for consistent results across a batch.
- Preserve the source date rather than implying a real-time enrollment check.
- Export explicitly missing lookup results instead of silently losing supplied NPIs.
- Reject unexpected upstream schemas and ineffective filters.

### Getting started

1. Supply ten-digit NPI strings, or exact practitioner surname objects.
2. Set a global maximum result count.
3. Run the Actor and open the default dataset.
4. Inspect SUMMARY for the release date and whether the cap was reached.
5. Export results as CSV, JSON, or Excel using Apify dataset tools.

```json
{"npis":["1417051921"],"maxItems":100}
```

### Inputs

| Field | Meaning |
|---|---|
| npis | Up to 1000 ten-digit strings; leading zeroes remain intact |
| names | Up to 100 objects containing exact lastName and optional exact firstName |
| maxItems | Global output cap, 1–10000; default 10 |

At least one NPI or name query is required. Names are trimmed and uppercased, then matched exactly. There is no fuzzy matching, state search, wildcard mode, or full-roster extraction.

```json
{"names":[{"lastName":"SMITH","firstName":"A"}],"maxItems":10}
```

### Output fields

| Field | Meaning |
|---|---|
| query | Exact CMS filter used to find this result |
| membership | listed or not\_listed in this snapshot |
| npi | Source NPI, or requested NPI on a missing result |
| firstName / lastName | CMS names; null for missing results |
| PARTB | Source Part B ordering/referring flag |
| DME | Source durable medical equipment flag |
| HHA | Source home health agency flag |
| PMD | Source power mobility device flag |
| HOSPICE | Source hospice flag |
| sourceReleaseDate | CMS release date, not enrollment start date |
| sourceUrl | Official dataset landing page |
| snapshotApiUrl | Dated API used for the lookup |
| scrapedAt | Retrieval timestamp |
| interpretation | Missing-result warning, when applicable |

Flags map Y to true and N to false. All flags are null on not-listed rows: absence never means five negative eligibility findings.

### Example result

This is a representative official public record from local verification:

```json
{
  "query":{"NPI":"1417051921"},
  "membership":"listed",
  "npi":"1417051921",
  "firstName":"N",
  "lastName":"A BELLE",
  "PARTB":false,
  "DME":true,
  "HHA":false,
  "PMD":true,
  "HOSPICE":false,
  "sourceReleaseDate":"2026-09-29"
}
```

The full result also contains source URLs and a retrieval timestamp.

### PECOS enrollment limitations

Not listed does **not** mean unenrolled in Medicare. This is a limited ordering/referring dataset, not private PECOS enrollment status, PTAN lookup, revocation screening, revalidation, opt-out screening, or Medicare billing authorization. Use official CMS guidance and appropriate enrollment sources for a complete determination.

Name searches can return several practitioners. Confirm identity using NPI; do not treat a shared name as proof. Duplicate listed NPIs are emitted once per run, attributed to the first matching query. A no-match query produces one not-listed row. Reaching maxItems can skip remaining queries or truncate a name result set.

### How much does it cost to check CMS ordering eligibility?

Pricing is charged per run start and each emitted lookup result, including a useful not-listed result. No separate detail-page event is charged. The start fee is $0.04 per run. Result prices follow your qualifying aggregate monthly Apify Store spend tier, not a private per-Actor volume schedule:

| Tier | Price per result |
|---|---|
| FREE | $0.00115 |
| BRONZE | $0.001 |
| SILVER | $0.00078 |
| GOLD / PLATINUM / DIAMOND | $0.0006 |

At BRONZE, estimated Actor charges are $0.041 for one result, $0.045 for five, and $0.14 for 100. At FREE, 100 results cost an estimated $0.155. Consult the active Pricing tab and your Apify plan for applicable platform costs. These are estimates, not guaranteed invoices; adjustments, refunds, disputes, taxes, corrections, and clawbacks may apply.

### Integrations

Export CSV to a credentialing spreadsheet, retrieve JSON into a billing validation pipeline, or schedule periodic Apify runs and compare NPI/flag combinations in your own database. Preserve sourceReleaseDate in comparisons: a changed release date alone is not an eligibility change. Native alerts and cross-run delta tracking are not provided.

### API usage

Use your own Apify API token; never expose it in shared spreadsheets.

```bash
curl -X POST -H "Authorization: Bearer $APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  'https://api.apify.com/v2/acts/automation-lab~cms-pecos-medicare-enrollment-lookup/run-sync-get-dataset-items' \
  -d '{"npis":["1417051921"],"maxItems":100}'
```

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/cms-pecos-medicare-enrollment-lookup').call({ npis: ['1417051921'] });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

```python
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/cms-pecos-medicare-enrollment-lookup').call(run_input={'npis': ['1417051921']})
print(client.dataset(run['defaultDatasetId']).list_items().items)
```

### MCP usage

Claude Code:

```bash
claude mcp add --transport http apify "https://mcp.apify.com?tools=automation-lab/cms-pecos-medicare-enrollment-lookup"
```

Claude Desktop, Cursor, and VS Code can use equivalent HTTP MCP configuration with Apify authentication configured in their client:

```json
{"mcpServers":{"apify":{"url":"https://mcp.apify.com?tools=automation-lab/cms-pecos-medicare-enrollment-lookup"}}}
```

Example prompt: “Check these NPIs in the current CMS Order and Referring snapshot and export the flags and release date. Explain that missing membership is not unenrollment.”

### Legality and responsible use

The source is a public CMS dataset. Respect CMS and Apify terms, minimize unnecessary personal-data retention, and apply your organization's credentialing controls. This Actor is independent and is not affiliated with or endorsed by CMS. It is a data retrieval tool, not legal, clinical, or enrollment advice.

### Data handling and support

No AI model, external paid API, proxy, or private PECOS credential is used at runtime. Query NPIs and names are sent to the public CMS API. Public practitioner identity and eligibility flags are saved to your run's default dataset; SUMMARY is saved to its key-value store. Do not supply patient information, private credentials, or other sensitive data.

Results, inputs, and logs remain in your Apify account under your storage and retention settings until removed or expired. The Actor has no separate persistent cache, cross-run database, or automatic deletion schedule. Delete datasets, key-value stores, and run records through Apify when no longer needed. Keep exports only for your required credentialing retention period. Apify provides hosting/storage and CMS receives the lookup requests; no other runtime recipient is used.

Report reproducible problems through the Actor's Apify Store Issues tab with the relevant run link and non-sensitive input. Never include API tokens or patient information.

### Troubleshooting and FAQ

**Why was my NPI missing?** It was not listed in the selected snapshot. Consult other official sources; do not infer unenrollment.

**Why did fewer queries finish?** maxItems applies globally. Increase it or split the batch; SUMMARY reports whether the limit was reached.

**Why did the run fail?** Invalid input, unavailable CMS APIs, or a changed schema cause an explicit failure. Temporary upstream failures receive at most three attempts. There is no proxy or browser fallback.

**Can I search by partial name?** No. Supply the exact CMS spelling of surname and optionally first name.

**Does this check a private PECOS account?** No. It only checks the public ordering/referring extract.

### Related Actors

Use [NPPES NPI Registry Provider Search](https://apify.com/automation-lab/npi-registry-provider-search) for provider identity and taxonomy. NPPES registration is not Medicare enrollment or ordering eligibility. Use [CMS Open Payments Data](https://apify.com/automation-lab/cms-open-payments-data) for payment transparency records, not eligibility decisions.

# Changelog

This Actor's version history is a separate document: https://apify.com/automation-lab/cms-pecos-medicare-enrollment-lookup/changelog.md

# Actor input Schema

## `npis` (type: `array`):

Up to 1000 ten-digit NPI strings. No private account is used.

## `names` (type: `array`):

Up to 100 objects with exact lastName and optional exact firstName. Case is normalized to uppercase; names can match multiple practitioners.

## `maxItems` (type: `integer`):

Global cap including not-listed lookup results. Remaining queries may be skipped when reached; see SUMMARY.

## Actor input object example

```json
{
  "npis": [
    "1417051921"
  ],
  "maxItems": 10
}
```

# Actor output Schema

## `dataset` (type: `string`):

Lookup records, including explicit not-listed results.

## `summary` (type: `string`):

Result count, release date and cap indicator.

# 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 = {
    "npis": [
        "1417051921"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/cms-pecos-medicare-enrollment-lookup").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 = { "npis": ["1417051921"] }

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/cms-pecos-medicare-enrollment-lookup").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 '{
  "npis": [
    "1417051921"
  ]
}' |
apify call automation-lab/cms-pecos-medicare-enrollment-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/cms-pecos-medicare-enrollment-lookup"
        }
    }
}
```

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/PVASdRSwO8AeVLm6F/builds/NsxVJer9pJep3HlVo/openapi.json