# CMS Procedure Reimbursement — HCPCS by Locality, Per Record (`nexgensignal/cms-procedure-reimbursement-records`) Actor

CMS Physician/Supplier Procedure Summary (PSPS) as clean per-record reimbursement benchmarks - submitted/allowed/denied counts and charge/payment amounts by HCPCS code, specialty and locality. No NPI. Public-domain, $0.05 per record.

- **URL**: https://apify.com/nexgensignal/cms-procedure-reimbursement-records.md
- **Developed by:** [NexGen Signal](https://apify.com/nexgensignal) (community)
- **Categories:** Business, Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $33.50 / 1,000 procedure reimbursement records

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## CMS Procedure Reimbursement — HCPCS by Locality, Per Record

Turn CMS's Physician/Supplier Procedure Summary into clean, per-record reimbursement benchmarks - one row per HCPCS procedure code x specialty x carrier x pricing locality x place-of-service, with submitted, allowed and denied service counts and charge/payment amounts, ready for provider-network analysts to benchmark allowed payments.

Each row from the CMS data API becomes **one clean, flat record** with numeric fields coerced to real
numbers, CMS's `*`-suppressed cells delivered as `null` (not zero), a stable `record_id`, and provenance
stamped on every row: source, dataset UUID, the public-domain notice, attribution, a UTC retrieval
timestamp and an interpretation caveat.

### What one record represents

The source is the U.S. Centers for Medicare & Medicaid Services (CMS) open data API — dataset
**`164fc736-4179-4100-9f79-592b69e41975`**, *Medicare Physician/Supplier Procedure Summary (PSPS)*. Each record is **one procedure summary cell**: a HCPCS/CPT code (with modifiers) for a specialty code, carrier, pricing locality, type-of-service and place-of-service, carrying submitted/allowed/denied service counts and charge amounts and the NCH payment amount. `specialty_code` is a specialty code, not a provider - there is no NPI or provider name anywhere in the dataset.

For each record you get the analytic columns listed below (reproduced verbatim, numbers as numbers) plus
a composite `record_id` and the provenance block. Columns include `hcpcs_code` (+ initial/second modifiers), `specialty_code`, `carrier_number`, `pricing_locality_code`, `type_of_service_code`, `place_of_service_code`, `submitted_service_count`, `submitted_charge_amount`, `allowed_charge_amount`, `denied_services_count`, `nch_payment_amount` and `betos_code`.

### Coverage and volume

The full dataset holds **14,474,585** procedure-summary rows across every HCPCS code, specialty, locality and place-of-service. Because that is far too large to return whole, this Actor pulls **one HCPCS code at a time** via a required input (a single common code such as 99213 already yields ~180,000 rows).

**Live full-dataset count is 14,474,585 records - matches the Wave-3 index figure exactly; that whole-dataset figure is the capacity line, retrieved one HCPCS code per run.**

The Actor filters the CMS data API to your chosen HCPCS code (`filter[HCPCS_CD]`) and pages within it (`size`/`offset`), stopping at your Maximum records cap.

### Licence and attribution

CMS open data is a **public-domain U.S. Government work** (17 U.S.C. §105) — free to use, redistribute
and build on. The developer FAQ that governs the API is published by CMS; the full notice travels on
every record:

> U.S. CMS (Centers for Medicare & Medicaid Services). Public-domain U.S. Government work (17 U.S.C. 105). Reproduced verbatim; no third-party content. Aggregate procedure-summary rows only - no provider, NPI, or beneficiary data.

The required attribution — `U.S. Centers for Medicare & Medicaid Services (CMS)` — is present on every record.

### Interpretation caveat

Aggregate Medicare procedure summary (PSPS). Charge and payment amounts are Medicare-allowed and NCH-paid figures, not provider list prices. specialty\_code is a specialty code, not a provider; there is no NPI or provider name.

Values are reproduced verbatim from the API. CMS suppresses small cells with an asterisk (`*`) for
privacy; those are delivered as `null` so you can tell "suppressed" apart from a real zero. The indicator fields (`asc_indicator`, `error_indicator`) are reproduced verbatim as codes.

### Person-data policy

There is no provider, NPI, or beneficiary data in this dataset - `specialty_code` is a coded specialty, and every other column is a code, count or amount. The field list this Actor emits is a fixed allow-list, and a per-record assertion
rejects any row that would introduce an NPI, provider-name, or contact field (verified with a planted-
field test). This is aggregate benchmark data about drugs, procedures, manufacturers and localities —
never about individual patients or providers.

### Data quality and freshness

Numeric fields are coerced to real numbers and booleans to real booleans; suppressed cells become
`null`. Every run re-reads the live API, so the data is as fresh as CMS publishes, and each record's
`observed_at` stamp records when it was retrieved. Delivery is in the API's order and keyed on the
source-native composite, so the dataset is safe to diff, deduplicate or upsert. The run's `RUN_RECEIPT`
records the API's reported total row count alongside how many records were delivered and charged.

### Provenance and compliance

Every run reads `data.cms.gov/robots.txt` at runtime; the gate result (URL, status, byte length, SHA-256
of the policy) is written to the run's `RUN_RECEIPT`. The API is keyless. The Actor never bypasses a
block or fetches through a mirror.

### Inputs

- **HCPCS code** (`hcpcsCode`, required) - the procedure code to pull (e.g. 99213 office visit, 99233 hospital care). The dataset is too large to pull whole, so it is retrieved one code at a time.
- **Maximum records** (`maxRecords`) — hard cap on records delivered and billed.

### Output

Records land in the Actor's default dataset and export as JSON, CSV, Excel or via the Apify API. A
tabular **overview view** surfaces the most useful columns for quick inspection.

### Fields in detail

The record leads with the HCPCS code and its dimension codes (specialty, carrier, locality, type- and place-of-service), then the service counts and charge/payment amounts. The provenance block — `source`, `source_dataset`, `licence`, `attribution`,
`caveat`, `observed_at` — closes every record, so a single row is self-describing and audit-ready.

### Working with CMS suppression

CMS suppresses small cells with an asterisk (`*`) to protect privacy. This Actor maps every suppressed
numeric cell to `null` rather than to zero or the literal string `*`, so your downstream aggregations do
not silently treat a suppressed value as a real number. A `null` in a count or amount column therefore
means "CMS suppressed this cell", not "reported zero" — an important distinction when you sum or average
across rows. Text and code columns are always passed through verbatim, so codes such as HCPCS, BETOS,
carrier and locality remain exactly as CMS publishes them and join cleanly against CMS reference tables.

### Scaling and limits

Set **Maximum records** low to sample cheaply or high to pull the full set (or, for the partitioned
dataset, the full slice for your chosen code). The Actor pages the API server-side and delivers
incrementally, so memory stays flat regardless of how many records you request, and you are billed only
for what is delivered. Because CMS refreshes these datasets on its own publication calendar, re-running
the Actor picks up new periods automatically, and each record's `observed_at` stamp dates the snapshot —
schedule a run to keep a downstream benchmark table current.

### Sibling Actors

This Actor benchmarks **procedure reimbursement** at the aggregate (specialty x locality) level. It complements the fleet-1 **Medicare Provider Intelligence** cell (provider-level intelligence) - aggregate reimbursement benchmarks versus provider-level detail are two different jobs. This Actor also shares its engineering — the runtime robots gate, push-then-charge
billing and verbatim-value discipline — with the fleet's other public-data records Actors.

### Pricing

This Actor uses Apify's pay-per-event model: a flat **$0.05 per record** actually delivered to the
dataset, and nothing else — no monthly rental, no per-run base fee, no compute charge. Deliver 40
records and you pay $2.00; deliver 10,000 and you pay $500.00. Billing is wired *after* delivery — each
record is pushed first and only then does the per-record event fire — so a mid-run failure can only
ever under-charge you, never over-charge. Use **Maximum records** to cap spend precisely.

### Typical uses

Benchmark Medicare allowed payments by procedure, specialty and locality; compare submitted versus allowed versus paid amounts; screen denial rates by code; build a fee-schedule reference; or feed a provider-network, contracting or revenue-cycle model with clean reimbursement records.

### What this Actor does not do

It does not deliver provider-level, NPI-level, or beneficiary-level data — it is an **aggregate benchmark**
table; it does not forecast or model; and it does not alter any published value beyond coercing types and
mapping CMS's `*` suppression to `null`. It gives you faithful, public-domain, analysis-ready records with
a provenance trail you can audit on every run.

# Actor input Schema

## `hcpcsCode` (type: `string`):

The dataset has 14.4M rows, so it is pulled one HCPCS procedure code at a time. Enter a HCPCS/CPT code (e.g. 99213 office visit, 99233 hospital care).

## `maxRecords` (type: `integer`):

Maximum records delivered and billed. You are billed only for records delivered.

## Actor input object example

```json
{
  "hcpcsCode": "99213",
  "maxRecords": 500
}
```

# Actor output Schema

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

The delivered CMS procedure reimbursement record.

# 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 = {
    "hcpcsCode": "99213",
    "maxRecords": 500
};

// Run the Actor and wait for it to finish
const run = await client.actor("nexgensignal/cms-procedure-reimbursement-records").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 = {
    "hcpcsCode": "99213",
    "maxRecords": 500,
}

# Run the Actor and wait for it to finish
run = client.actor("nexgensignal/cms-procedure-reimbursement-records").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 '{
  "hcpcsCode": "99213",
  "maxRecords": 500
}' |
apify call nexgensignal/cms-procedure-reimbursement-records --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nexgensignal/cms-procedure-reimbursement-records"
        }
    }
}

```

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/a1R5bkcPutnrUsreI/builds/GWgJ4CyaKaIe4iIuj/openapi.json