# Healthcare Provider Credential Check (NPI + OIG LEIE + SAM.gov) (`golden_shores_agentics/provider-credential-check`) Actor

Verify US healthcare providers in one call: confirms the NPI in CMS NPPES, screens the HHS-OIG LEIE exclusion list (optionally SAM.gov), cross-checks a license number, and returns one clear / excluded / review / not\_found verdict with evidence. Built for AI agents; pay per provider.

- **URL**: https://apify.com/golden\_shores\_agentics/provider-credential-check.md
- **Developed by:** [John Seimon](https://apify.com/golden_shores_agentics) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$10.00 / 1,000 provider checks

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

### What does Healthcare Provider Credential Check do?

**Healthcare Provider Credential Check** verifies a US healthcare provider in one call. Give it an **NPI** (or a name + state, or an organization name) and it confirms the record in the **CMS NPPES NPI Registry**, screens the provider against the **HHS-OIG LEIE exclusion list** (List of Excluded Individuals/Entities), optionally screens **SAM.gov federal exclusions**, cross-checks a **state license number** against NPPES-reported licenses, optionally **verifies that license directly with the state licensing board** (Washington and Colorado), and returns a single **verdict** — `clear`, `excluded`, `review` or `not_found` — with the evidence behind it.

It is an **NPI lookup API**, an **OIG exclusion screening API** and a **provider verification API** in one, built for **AI agents** and automated credentialing, vendor onboarding, claims and compliance workflows: normalized input, normalized output, deterministic logic (no LLM guessing), and pay-per-provider pricing.

### Why use Healthcare Provider Credential Check?

- **One call, three sources.** NPPES, OIG LEIE and (optionally) SAM.gov are checked together and reconciled into one verdict, instead of three separate lookups and hand-written matching logic.
- **Evidence, not opinions.** Every result carries the source URL, the LEIE list date, the match strength (`npi`, `name_dob`, `name_state`, `business_name` or weak `name_only`) and the exact exclusion row, so an agent or an auditor can see *why*.
- **Built for agentic use.** Clean, described input schema; flat, typed output fields; `ref` passthrough to join results to your own records; graceful stop when a spend cap is reached. Discoverable and callable through the Apify MCP server and payable with x402.
- **Deterministic and cheap.** Rules-based matching over official data — the same input always gives the same output, at a fraction of a cent per provider.
- **Monthly compliance friendly.** Re-run the same list every month (OIG recommends monthly screening); results are dated with the LEIE file version used.

### What data does Healthcare Provider Credential Check return?

Each provider becomes one dataset item:

| Field | Type | Description |
|---|---|---|
| `ref` | string | null | Your own id, echoed back |
| `verdict` | string | `clear`, `excluded`, `review` or `not_found` |
| `reasons` | string\[] | Plain-language reasons behind the verdict |
| `npi` | string | null | NPI used for the check |
| `providerName` | string | null | Individual or organization name from NPPES |
| `nppesStatus` | string | null | `A` active, `D` deactivated |
| `oigExcluded` | boolean | Strong OIG LEIE match (not reinstated) |
| `oigMatchCount` | integer | LEIE rows matched, including weak name-only matches |
| `samChecked` / `samExcluded` | boolean | SAM.gov screening status and result |
| `licenseNumberMatchesNppes` | boolean | null | Whether the supplied license number appears in NPPES |
| `licenseStatus` | string | null | State board status: `active`, `expired`, `suspended`, `revoked`, `probation`, `inactive`, `not_found`, `unavailable` |
| `licenseExpiresAt` | string | null | Expiry date the board holds (YYYY-MM-DD) |
| `licenseDisciplineFlag` | boolean | null | Board action recorded against the license |
| `licenseBoardUrl` | string | null | Where a human can confirm the license |
| `licenseConfidence` | string | null | `high`, `medium` or `low` — how well the board record was tied to the person |
| `checkedAt` | string | ISO-8601 timestamp |
| `leieListDate` | string | Date of the OIG LEIE file used |
| `billed` | boolean | `false` for invalid queries returned unbilled |
| `detail` | object | Full NPPES record (taxonomies, licenses, addresses), every LEIE match with its row, SAM matches, evidence URLs and warnings |

#### How the verdict is decided

| Verdict | Meaning |
|---|---|
| `clear` | NPPES record found (NPI confirmed, or exactly one name match); no strong OIG/SAM exclusion; license number (if given) matches |
| `excluded` | A strong LEIE match — by NPI, by name **and** DOB, by name **and** state, or by business name — that has no reinstatement date; or an active SAM.gov exclusion |
| `review` | Something needs a human or a second look: only a weak name-only LEIE match, NPI is deactivated, a name search matched several NPPES records, the license number does not match NPPES, or the state board reports the license as anything other than a confidently matched active one |
| `not_found` | NPPES returned no record for the NPI / name supplied |

Weak name-only LEIE matches never set `excluded` on their own, because common names produce false positives; they are surfaced as `review` with the LEIE row (including DOB and address) so you can confirm.

#### State license verification (WA, CO)

Turn on **Also verify license with the state board (WA, CO)** and give a provider a `licenseNumber` together with `state: "WA"` or `state: "CO"`. The Actor then queries that state's own licensee register live, per provider, and returns what the board itself says about the license:

- **status** — the board's wording (`Active`, `Expired`, `Suspended`, `Revoked`, `Probation`, …) preserved as `detail.license.rawStatus` and normalized into `licenseStatus`;
- **dates** — first issue date and expiry date, as `licenseIssuedAt` / `licenseExpiresAt` in `detail.license`. If a board calls a license active while its expiry has passed, the board's wording wins and the result carries an `expiration_in_past` warning rather than a silently changed status;
- **discipline** — `licenseDisciplineFlag`, plus the case number, action, effective and completion dates for every case the register publishes (Colorado publishes one row per case; they are aggregated into a single license);
- **who holds it** — the licensee's name from the register. When a name is available (yours, or the one NPPES has for the NPI) it must agree with the board record for `licenseConfidence: "high"`; with no name to check against, the match is `medium`; a disagreement sets `nameMismatch` and forces `review`, because a license number alone does not prove identity — Colorado license numbers, for instance, are not unique across license types;
- **evidence** — `licenseBoardUrl` (the board's verification deep link where the register publishes one, otherwise the board's public lookup page), the board name, and `detail.license.evidence.sourceAsOf`, the date the state last refreshed the register.

The sources are the states' own public open-data registers: the **Washington State Department of Health** health-care provider credential data and the **Colorado DORA** Division of Professions and Occupations licensee data. Nothing is scraped and no login is used; a free Socrata app token can be supplied in **Socrata app token** to raise the rate limit on large runs.

A state board result never sets `excluded` on its own — a board action is not an OIG exclusion — but a license that is suspended, revoked, on probation, expired, inactive, unknown to the board, or held by a different name moves the verdict to `review` with the reason attached. Providers in states other than WA and CO come back with a `state_license_unsupported` warning and an unchanged verdict.

Billing: state license verification is billed as a separate `license-verified` event when a board answer is obtained; it is not billed when the board is unreachable or the state is unsupported.

### How to verify a healthcare provider

1. Open the Actor and paste NPIs into **NPIs** (or add providers by name in **Providers**).
2. Optionally turn on **Also screen SAM.gov exclusions** and add a free [api.data.gov](https://api.data.gov/signup/) key, and/or **Also verify license with the state board (WA, CO)** for providers whose `licenseNumber` and `state` you have.
3. Click **Start**. Results appear in the dataset within seconds; download as JSON, CSV or Excel, or read them via the API.

From an AI agent: call the Actor through the [Apify MCP server](https://mcp.apify.com) (`search-actors` → `call-actor`), or via the REST API with your token. The `ref` field lets the agent join results back to its own list.

### How much does it cost to verify a provider?

Pricing is **pay per event**: **one `provider-check` event per provider actually checked**, whether or not the provider is found. Two kinds of item are returned with `billed: false` and are **not charged**: invalid inputs (bad NPI check digit, no name, bad state code) and results produced while a source was unavailable (`sourcesDegraded: true`). State license verification is billed as a separate **`license-verified`** event when a board answer is obtained; it is not billed when the board is unreachable or the state is unsupported. There is no start fee and no per-item fee.

Set **Max total charge** on the run to cap spend; the Actor stops cleanly at the cap and tells you how many providers were checked.

### Input

```json
{
  "npis": ["1234567893"],
  "providers": [
    { "firstName": "Jane", "lastName": "Smith", "state": "TX", "ref": "row-2" },
    { "organizationName": "Sunrise Clinic LLC", "state": "AZ", "ref": "row-3" },
    { "npi": "1003000134", "licenseNumber": "036-123456", "state": "IL", "ref": "row-4" }
  ],
  "checkSam": false,
  "checkStateLicense": false,
  "maxProviders": 500
}
```

- `npis` — list of 10-digit NPIs (fastest, most precise).
- `providers` — objects with `npi`, or `firstName` + `lastName` (+ `state`, `dob`), or `organizationName`; optional `licenseNumber` and `ref`.
- `checkSam` + `samApiKey` — add SAM.gov federal exclusion screening.
- `checkStateLicense` (+ optional `socrataAppToken`) — verify `licenseNumber` with the state board for providers in WA or CO.
- `maxProviders` — safety cap per run.

### Output

```json
{
  "ref": "row-1",
  "verdict": "excluded",
  "reasons": ["OIG LEIE: npi match, excluded 20200115 (1128b4)"],
  "npi": "1234567893",
  "providerName": "JOHN A DOE",
  "nppesStatus": "A",
  "oigExcluded": true,
  "oigMatchCount": 1,
  "samChecked": false,
  "samExcluded": false,
  "licenseNumberMatchesNppes": null,
  "licenseStatus": null,
  "licenseExpiresAt": null,
  "licenseDisciplineFlag": null,
  "licenseBoardUrl": null,
  "licenseConfidence": null,
  "checkedAt": "2026-09-15T12:00:00.000Z",
  "leieListDate": "2026-09-01",
  "billed": true,
  "detail": {
    "nppes": { "npiConfirmed": true, "record": { "npi": "1234567893", "enumerationType": "NPI-1", "licenses": [{ "taxonomyCode": "207Q00000X", "taxonomyDescription": "Family Medicine", "licenseNumber": "036-123456", "state": "IL", "primary": true }] } },
    "oig": { "excluded": true, "listDate": "2026-09-01", "matches": [{ "strength": "npi", "row": { "lastName": "DOE", "firstName": "JOHN", "npi": "1234567893", "state": "IL", "exclusionType": "1128b4", "exclusionDate": "20200115", "reinstatementDate": "" } }] },
    "evidence": [
      { "source": "NPPES", "url": "https://npiregistry.cms.hhs.gov/api/?version=2.1&limit=10&number=1234567893", "note": "matched NPI 1234567893" },
      { "source": "OIG_LEIE", "url": "https://exclusions.oig.hhs.gov/", "note": "LEIE dated 2026-09-01; 1 match(es)" }
    ],
    "warnings": []
  }
}
```

Download the dataset as JSON, CSV, Excel, XML or RSS from the **Storage** tab, or fetch it through the API.

### Tips

- **Prefer NPIs.** Name searches can match several NPPES records; the Actor uses the first and lists the other candidate NPIs under `review`.
- **Supply `state` and `dob`** with names — a matching DOB (or state) turns a weak name-only LEIE match into a strong match, and a *different* DOB rules a row out; `state` also narrows NPPES results.
- **Monthly re-screening:** schedule the Actor with the same input each month; compare `verdict` and `leieListDate` across runs.
- **Large lists:** batches of thousands of providers work; NPPES is queried once per provider, the LEIE is loaded once per run (cached for 24 hours).

### FAQ, disclaimers and support

**Is this an official CMS or OIG service?** No. It reads the public NPPES API and the public OIG LEIE download and applies documented matching rules. Always confirm an `excluded` or `review` result against the official sources linked in `evidence` before taking action against a provider.

**Does it verify state licenses with the state boards?** For **Washington** and **Colorado**, yes — turn on **Also verify license with the state board (WA, CO)** and the license is checked against the state's own register (see above). For every other state the license number is only compared with what the provider reported to NPPES, which is self-reported.

**How fresh is the data?** NPPES is queried live, and so are the WA and CO license registers — each result carries the date the state last refreshed its register under `detail.license.evidence.sourceAsOf`. The LEIE is downloaded from OIG at most once per 24 hours; the file date is returned as `leieListDate`.

**Legality and ethics.** All sources are public US government datasets published for exactly this purpose. Do not use results to discriminate unlawfully; follow your organization's credentialing policy.

Found a problem or need another source? Open an issue on the Actor's **Issues** tab.

# Actor input Schema

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

List of 10-digit National Provider Identifiers to check. Fastest and most accurate input. Example: \["1234567893"]. Use `providers` instead when you only have names.

## `providers` (type: `array`):

Array of provider objects. Each object may contain: npi (10 digits), firstName, lastName, organizationName, state (2-letter), dob (YYYY-MM-DD), licenseNumber (compared with NPPES-reported licenses), ref (any string echoed back in the result). Provide npi OR lastName (+firstName, state, dob) OR organizationName.

## `checkSam` (type: `boolean`):

When true, each provider is also screened against the SAM.gov federal exclusions list. Requires samApiKey (free key from api.data.gov). Off by default.

## `samApiKey` (type: `string`):

Free api.data.gov key used for SAM.gov exclusion screening. Only needed when checkSam is true.

## `checkStateLicense` (type: `boolean`):

When true, a provider given with a licenseNumber and a state of WA or CO is verified directly against that state's licensing board register (Washington DOH, Colorado DORA): status, expiry and board discipline. Providers in any other state are returned unverified with a state\_license\_unsupported warning. Off by default.

## `socrataAppToken` (type: `string`):

Optional free Socrata app token (data.wa.gov / data.colorado.gov). Not required; it raises the anonymous rate limit for large runs with checkStateLicense on.

## `maxProviders` (type: `integer`):

Safety cap on how many providers are checked (and billed) in this run.

## Actor input object example

```json
{
  "npis": [
    "1234567893"
  ],
  "providers": [
    {
      "firstName": "Jane",
      "lastName": "Smith",
      "state": "TX",
      "ref": "row-1"
    }
  ],
  "checkSam": false,
  "checkStateLicense": false,
  "maxProviders": 500
}
```

# Actor output Schema

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

Dataset of check results. Each item has verdict (clear | excluded | review | not\_found), reasons, NPPES record, OIG LEIE matches, SAM matches, the state board license verification (licenseStatus, licenseExpiresAt, licenseDisciplineFlag, licenseBoardUrl, licenseConfidence) and evidence URLs.

# 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": [
        "1234567893"
    ],
    "providers": [
        {
            "firstName": "Jane",
            "lastName": "Smith",
            "state": "TX",
            "ref": "row-1"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("golden_shores_agentics/provider-credential-check").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": ["1234567893"],
    "providers": [{
            "firstName": "Jane",
            "lastName": "Smith",
            "state": "TX",
            "ref": "row-1",
        }],
}

# Run the Actor and wait for it to finish
run = client.actor("golden_shores_agentics/provider-credential-check").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": [
    "1234567893"
  ],
  "providers": [
    {
      "firstName": "Jane",
      "lastName": "Smith",
      "state": "TX",
      "ref": "row-1"
    }
  ]
}' |
apify call golden_shores_agentics/provider-credential-check --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,golden_shores_agentics/provider-credential-check"
        }
    }
}
```

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/dnRgeLthxvtRZ19ov/builds/qt0H6REL7i46c2vAm/openapi.json