CMS Opt Out Affidavit Delta

Monitors named NPIs (National Provider Identifiers) in the official, free, public CMS Opt Out Affidavits registry (data.cms.gov) and reports only genuine changes since your last check:

• added — a new opt-out affidavit is published for an NPI you watch (the provider has opted out of Medicare participation);
• status_changed — an already-known opt-out record changes its actual status:

  Eligible to Order and Refer
  flips, or the Optout End Date moves (a renewal or a shortened window);
• removed — the NPI is confirmed gone from the registry (rejoined Medicare, or the opt-out lapsed without renewal). Confirmed only after two consecutive monthly checks find it missing — a single miss is reported as an unpaid removal_candidate signal, never billed;
• name, specialty, or address edits alone are not billed — only the two status fields above matter.

You are billed once per real change, not per row returned and not per run. A run that finds nothing new is free.

Why this exists

The source dataset (Opt Out Affidavits, described by

describedBy: https://data.cms.gov/resources/opt-out-affidavits-data-dictionary

Two competing tools were checked before building this (both confirmed live, via their own published descriptions): one bills per delivered record on every run regardless of whether anything changed, the other is an explicit snapshot/export tool that detects which datasets were updated, not which individual records changed. Neither offers a durable per-NPI delta with pay-per-real-event billing.

Input

• monitorId — a stable name for this monitor's durable history (^[a-z0-9-]{1,40}$).
• watches — 1 to 25 objects {"watchId": "dr-smith", "npi": "1720444581"}. npi must be exactly 10 ASCII digits and is matched byte-for-byte against CMS's own NPI field — no normalization, no whitespace trimming, no leading-zero handling. You can add new watches under the same monitorId later; each watchId is permanently bound to the npi it was first used with.
• notifyOn — new_alerts (default, webhook only when something billable was delivered), always, or never.
• webhookUrl — optional HTTPS endpoint that receives a JSON digest of delivered (billed) changes.

Output

• Dataset — one row per delivered change, plus a run_summary row every run. Key fields: watchId, npi, status (added|status_changed|removed|removal_candidate), lastName/firstName/ specialty, optoutEffectiveDate/optoutEndDate, eligibleToOrderAndRefer (current or last-known), previousOptoutEndDate/previousEligibleToOrderAndRefer. removal_candidate rows carry

  billed: false
  — an early, unpaid signal that a second check will either confirm or retract.
• Key-value store — coverage (per-watch status/reason, requested/attempted/succeeded/failed counts, records delivered/billed, exactly what was charged for) and digest (a short human-readable summary).

Guarantees and honest limits

• At-most-once delivery and billing, not exactly-once: an atomic claim (RequestQueue.addRequest) is the only thing that can authorize a Dataset write and a paid event. If the run crashes after claiming but before finishing, the event can be lost (never delivered) but is never billed twice.
• This is an informational monitor of a published, monthly-refreshed registry — it does not confirm a provider's real-time opt-out status, and it is not a substitute for verifying directly with CMS before making a billing or credentialing decision based on it.
• If the source structurally changes its response shape mid-registry, affected watches are marked source_access_limited rather than silently producing wrong data — this is surfaced in coverage, the digest, and (if configured) the webhook payload.