From 483f1858619e2545fbb2d3c551e0afcc562d7fe2 Mon Sep 17 00:00:00 2001 From: justin Date: Sun, 7 Jun 2026 23:54:01 -0500 Subject: [PATCH] feat(healthcare): prove revalidation is real via official CMS data + self-verify Skepticism ("is this even real?") is the top objection. The data IS accurate (verified our subscribers' NPIs match the official CMS Revalidation Due Date List exactly), so this is a credibility-presentation fix: 1. Email: replace the plain detail row with an "Official record - CMS Medicare Revalidation Due Date List" card (NPI, legal name, due date, days overdue) plus a "Verify on CMS.gov" button. Clearly labeled as our presentation of public CMS data, not a CMS screenshot (no impersonation). 2. API: npi/lookup now pulls the revalidation due date LIVE from the public CMS dataset (data.cms.gov) instead of the empty local table, and returns a revalidation{ due_date, source, cms_legal_name, verify_url } proof object. 3. Tool: /tools/npi-compliance-check shows a live "official record" card with a self-verify link when CMS returns a due date. Builder now stores reval_due_date/days_overdue as separate attribs for the card (existing 194 subscribers backfilled from their detail string). --- api/src/routes/npi-lookup.ts | 75 ++++++++++++++++++- .../hc_campaigns/hc_revalidation_overdue.html | 37 +++++++-- scripts/build_healthcare_campaigns_cron.py | 5 ++ .../pages/tools/npi-compliance-check.astro | 34 +++++++++ 4 files changed, 143 insertions(+), 8 deletions(-) diff --git a/api/src/routes/npi-lookup.ts b/api/src/routes/npi-lookup.ts index eddb02a..d8985d1 100644 --- a/api/src/routes/npi-lookup.ts +++ b/api/src/routes/npi-lookup.ts @@ -35,6 +35,56 @@ async function nppesFetch(params: Record): Promise { } } +// Live, authoritative CMS "Revalidation Due Date List" lookup by NPI. This is +// the same public .gov dataset the provider can check themselves at +// data.cms.gov/tools/medicare-revalidation-list, so it is the strongest proof +// the due date is real (not from our database). Returns null on miss/error so +// callers fall back to the local companion table. +const CMS_REVAL_API = + "https://data.cms.gov/data-api/v1/dataset/3746498e-874d-45d8-9c69-68603cafea60/data"; + +interface CmsRevalRecord { + revalidation_due_date: string | null; + adjusted_due_date: string | null; + enrollment_type: string | null; + specialty: string | null; + enrollment_state: string | null; + legal_name: string | null; + source: "cms_live"; +} + +async function cmsRevalFetch(npi: string): Promise { + const controller = new AbortController(); + const timer = setTimeout(() => controller.abort(), 6000); + try { + const qs = `filter[National Provider Identifier]=${encodeURIComponent(npi)}`; + const resp = await fetch(`${CMS_REVAL_API}?${qs}`, { + signal: controller.signal, + headers: { Accept: "application/json" }, + }); + clearTimeout(timer); + if (!resp.ok) return null; + const rows = (await resp.json()) as any[]; + if (!Array.isArray(rows) || rows.length === 0) return null; + // Prefer the row with a concrete (non-TBD) due date. + const norm = (v: any) => (typeof v === "string" && v && v.toUpperCase() !== "TBD" ? v : null); + const row = + rows.find((r) => norm(r["Adjusted Due Date"]) || norm(r["Revalidation Due Date"])) || rows[0]; + return { + revalidation_due_date: norm(row["Revalidation Due Date"]), + adjusted_due_date: norm(row["Adjusted Due Date"]), + enrollment_type: row["Enrollment Type"] || null, + specialty: row["Enrollment Specialty"] || null, + enrollment_state: row["Enrollment State Code"] || null, + legal_name: row["Organization Name"] || [row["First Name"], row["Last Name"]].filter(Boolean).join(" ") || null, + source: "cms_live", + }; + } catch { + clearTimeout(timer); + return null; + } +} + type CheckStatus = "green" | "yellow" | "red" | "unknown"; interface ComplianceCheck { @@ -98,8 +148,11 @@ router.get("/api/v1/npi/lookup", async (req, res) => { const locationAddr = (result.addresses || []).find((a: any) => a.address_purpose === "LOCATION") || (result.addresses || [])[0] || null; const practiceState = locationAddr?.state || null; - // 2) Companion data joins (best-effort; tables may be empty pre-load) - const [revalRes, exclRes, optoutRes] = await Promise.all([ + // 2) Companion data joins. Revalidation comes LIVE from the public CMS + // Revalidation Due Date List (authoritative + provider-verifiable); the + // local table is a fallback only (it may be empty pre-load). + const [cmsReval, revalRes, exclRes, optoutRes] = await Promise.all([ + cmsRevalFetch(rawNpi), pool.query( `SELECT revalidation_due_date, adjusted_due_date, enrollment_type, specialty, enrollment_state FROM npi_revalidation_due WHERE npi = $1 ORDER BY id LIMIT 1`, @@ -119,7 +172,13 @@ router.get("/api/v1/npi/lookup", async (req, res) => { ).catch(() => ({ rows: [] as any[] })), ]); - const reval = revalRes.rows[0] || null; + // Prefer live CMS data; fall back to the local companion table. + const reval = cmsReval || revalRes.rows[0] || null; + const revalSource: "cms_live" | "local" | null = cmsReval + ? "cms_live" + : revalRes.rows[0] + ? "local" + : null; const excl = exclRes.rows[0] || null; const optout = optoutRes.rows[0] || null; @@ -289,6 +348,16 @@ router.get("/api/v1/npi/lookup", async (req, res) => { enumeration_date: enumerationDate ? fmtDate(enumerationDate) : null, last_updated: lastUpdated ? fmtDate(lastUpdated) : null, checks, + // Verification proof: the revalidation due date (when present) is from the + // live public CMS dataset the provider can check themselves. + revalidation: reval + ? { + due_date: (reval.adjusted_due_date || reval.revalidation_due_date) ?? null, + source: revalSource, + cms_legal_name: (reval as any).legal_name ?? null, + verify_url: "https://data.cms.gov/tools/medicare-revalidation-list", + } + : null, summary: { red: redCount, yellow: yellowCount, diff --git a/data/hc_campaigns/hc_revalidation_overdue.html b/data/hc_campaigns/hc_revalidation_overdue.html index 99cb61d..1f6f2af 100644 --- a/data/hc_campaigns/hc_revalidation_overdue.html +++ b/data/hc_campaigns/hc_revalidation_overdue.html @@ -21,11 +21,38 @@
If you do not revalidate, CMS will deactivate your Medicare billing privileges — claims stop paying and you must re-enroll from scratch, losing your effective date and any retroactive billing.
- - - - - + +
NPI{{ .Subscriber.Attribs.npi }}
Revalidation due{{ .Subscriber.Attribs.detail }}
Our service fee$599
+ +
+ + + +
+

Official record · CMS Medicare Revalidation Due Date List

+
+ + + + + +
Provider / NPI{{ .Subscriber.Attribs.npi }}
Enrolled as{{ .Subscriber.Attribs.practice }}
Revalidation due date{{ .Subscriber.Attribs.reval_due_date }}
StatusPAST DUE · {{ .Subscriber.Attribs.days_overdue }} days overdue
+

Source: CMS Revalidation Due Date List (data.cms.gov), refreshed monthly. Performance West is an independent compliance firm, not affiliated with CMS or Medicare.

+
+
+ + +
+

Don’t take our word for it — check the official CMS record.

+

Look up your NPI {{ .Subscriber.Attribs.npi }} on the U.S. government’s public Medicare Revalidation List and you’ll see the same due date above.

+ Verify on CMS.gov ↗ +
+ + + +
Our service fee to file it for you$599
diff --git a/scripts/build_healthcare_campaigns_cron.py b/scripts/build_healthcare_campaigns_cron.py index d0d09aa..cce80cd 100644 --- a/scripts/build_healthcare_campaigns_cron.py +++ b/scripts/build_healthcare_campaigns_cron.py @@ -205,6 +205,11 @@ def main(): "practice": r.get("name", ""), "specialty": r.get("specialty", ""), "state": r.get("state", ""), + # Separate fields so the email's "official CMS record" card can render + # the due date and overdue count cleanly (these mirror the authoritative + # CMS Revalidation Due Date List, verified to match by NPI). + "reval_due_date": r.get("reval_due_date", ""), + "days_overdue": str(r.get("days_overdue", "")), "detail": (f"{r.get('reval_due_date','')} ({r.get('days_overdue','')} days overdue)" if r.get("reval_status") == "overdue" else r.get("reval_due_date", "")), } diff --git a/site/src/pages/tools/npi-compliance-check.astro b/site/src/pages/tools/npi-compliance-check.astro index 87351d7..7bb3e9d 100644 --- a/site/src/pages/tools/npi-compliance-check.astro +++ b/site/src/pages/tools/npi-compliance-check.astro @@ -88,6 +88,9 @@ import Base from "../../layouts/Base.astro";
+ + +
@@ -267,6 +270,37 @@ import Base from "../../layouts/Base.astro"; } renderCta(data); + + // CMS verification proof: when the revalidation due date came from the + // live public CMS dataset, show it as an "official record" the provider + // can independently verify on CMS.gov. This is what converts skeptics. + const proof = document.getElementById("cms-proof"); + const rv = data.revalidation; + if (rv && rv.due_date && rv.source === "cms_live") { + proof.innerHTML = ` +
+
+

Official record · CMS Medicare Revalidation Due Date List

+
+
+
+
Provider / NPI
${data.npi}
+ ${rv.cms_legal_name ? `
Enrolled as
${rv.cms_legal_name}
` : ""} +
Revalidation due date
${rv.due_date}
+
+

Pulled live from the U.S. government’s public CMS dataset just now — this is not our data. Performance West is an independent compliance firm, not affiliated with CMS or Medicare.

+ + Verify this yourself on CMS.gov + + +
+
`; + proof.classList.remove("hidden"); + } else { + proof.classList.add("hidden"); + proof.innerHTML = ""; + } + document.getElementById("checked-at").textContent = "Checked at " + new Date().toLocaleString(); resultsEl.classList.remove("hidden"); document.getElementById("results").scrollIntoView({ behavior: "smooth", block: "start" });