A defensible menopause provider graph — Phase 2 shipped

CMS NPPES (NPI Registry)

Public domain · bulk download (~9.6M rows) + REST API

All US healthcare providers with an NPI. Includes taxonomy codes, primary practice address, state license number + state code (×15 slots — used for the sanctions cross-walk), and authoritative provider identity. The provider_ingest pipeline streams the bulk schema, filters to the curated menopause NUCC taxonomies, overlays the MSCP credential list (synthetic + self-reported), computes a graphScore, stamps lat/lng from the Census ZCTA gazetteer, and emits the 2,015-row directory the contract serves. Refresh runs in ~1m50s end-to-end via the tracked refresh_national.sh harness.

• PurposeAuthoritative provider identity. The NPI is the join key that everything else hangs off.

Census 2020 ZCTA Gazetteer

Public domain · ~33K ZIP centroids

Bundled in both the Python pipeline (provider_ingest/centroids.py) and the Next.js server runtime (lib/zip-centroids.ts) so build-time stamping (every NPPES row → lat/lng) and request-time resolution (patient ZIP → centroid) draw from one source. The directory ranks by Haversine distance whenever the patient ZIP centroid is known and at least one in-tier provider has its own; otherwise it gracefully falls back to graphScore-only ranking and reports sort: "score".

• PurposeReal distance ranking, not a 3-digit-prefix proxy. Powers the "4.2 mi away" chip on every recommendation.

State license-sanction overlays

Public domain · CA + NY + TX

Three live filters drop sanctioned providers at build time: CA Medi-Cal Suspended & Ineligible List (NPI-keyed CSV from CHHS), NY Professional Medical Conduct Board Actions (license-keyed via the NPPES Provider License Number cross-walk), Texas Medical Board All-Licenses (license-keyed, allowlist of explicit active-sanction dispositions — REVOKED / SUSPENDED BY BOARD / UNDER BOARD ORDER, not the noisy != NONE check). The June 2026 run filters 588 (CA) + 849 (NY) + 283 (TX) = 1,720 candidates total. FL is gated behind Azure AD B2C; NJ is PDF-only; landscape documented in the runbook.

• PurposePatient-safety filter that's verifiable from the response (provenance.dataset.sanctionedFilteredBySource) on every API call.

NPPES service-line signals

Derived · provider_ingest/signals.py

Six public-registry tokens detected from the NPPES credential text + taxonomy stack: facog (Fellow ACOG = board-certified OB/GYN), faafp (board-certified family medicine), face (board-certified endocrinology), whnp (Women's Health NP), cnm (Certified Nurse-Midwife), multi-taxonomy (≥2 menopause-relevant NUCC codes). Each contributes a +2% graphScore bump capped at +5% — bounded so a non-certified provider with all signals still falls behind a certified one at the same baseline. 22% of the directory carries at least one signal; honestly sub-ranks the relevant-local fallback tier.

• PurposeStrengthens the case for non-certified providers in metros where MSCP coverage is sparse, without inventing certifications.

Insurance acceptance overlay

Synthetic per-NPI today · partner feed-shaped

There's no public structured payer/in-network feed; a real implementation needs a paid partnership (Ribbon Health, Turquoise, etc.). Today insuranceAccepted is derived deterministically from a SHA-256 hash of the NPI, calibrated to plausible real-world participation rates (Medicare ~85%, Kaiser ~20%, ~3.8 plans per provider on average). Every Experience API response carries the synthetic caveat in provenance.sources. The shape is real (filter UX, contract, agent framing); replacing the synthesis with a real feed is a one-module swap.

• PurposeWire the in-network filter end-to-end so the partner integration is a drop-in, not a rebuild.

Clinic-site service detection

Derived · Pause-built

Phase-2-bis. NPPES-resident signals already cover board certifications and multi-specialty practice; clinic-site scraping would add explicit mentions of HRT / perimenopause / vasomotor services on the practice's own website. Caching, rate-limiting, robots.txt-respecting. No fetcher today — we don't ship a brittle scraper without an explicit need.

• PurposeDistinguishes general OB/GYNs who happen to see midlife patients from clinicians actually marketing menopause services.

Licensed MSCP feed (Menopause Society)

Partnership · The Menopause Society

Authoritative Menopause Society Certified Practitioner roster; gated on a partnership (terms-of-use prohibits scraping/republishing). Self-reported MSCP/NCMP credentials in the public NPPES record act as the floor today (~14 physicians nationally — rare but real). The pipeline is ready to union a licensed feed via the same MscpOverlay class once an agreement lands.

• PurposeDense certified coverage outside the demo metros. Today's directory has 15 certified providers; a real feed adds thousands.

Outcomes signal (closed loop)

Pause-internal · Phase 3

Once Pause has referrals flowing at scale, the patient and provider outcomes from each referral become the strongest possible scoring signal. Activates after the first ~1,000 referrals.

• PurposeThe actual moat. Every successful referral makes the graph better; every poor one downweights the destination.

Why NPPES is the right substrate

It is public domain, refreshed weekly, and used by every other healthcare data product. There is no licensing complication and no terms-of-use trap. The NPI is the join key in our synthetic mock today, anticipating live ingestion.

Why we don't just buy a vendor graph

The commercial provider graphs (Definitive Healthcare, IQVIA OneKey, etc.) are excellent for general healthcare. None of them score for menopause specifically. We would still need to build the menopause overlay — so we just build the whole thing.

Why this will be a moat

Once Pause is producing referrals at scale, the outcome data we capture from each referral is uncopyable. The graph improves with every patient we serve. New entrants have to start at zero. Compounding starts at Phase 3.

Compliance posture

Everything ingested today is public-domain (NPPES, Census ZCTA, CHHS Medi-Cal S&I, NY OPMC, TX TMB). We carry provenance on every API response — sources list, dataset block with generatedAt + sourceDate + per-source sanction counts, synthetic-data callouts wherever the value is derived. Sanctioned providers are filtered at build time, not surfaced with a warning. Provider opt-out mechanism is designed (when needed); the licensed Menopause Society MSCP feed waits on a partnership rather than a scrape.

Phase 0 — Contract + mock

Shipped

Experience API contract at /api/mulesoft/providers with the full filter surface (zip, menopauseOnly, limit, fallback, insurance, distance) and a provenance block. MCP find_menopause_providers wraps it for LLM clients. The mock + the live MuleSoft CloudHub 2.0 worker honor the same contract; a vitest pins shape parity so they can't drift.

Phase 1 — NPPES + taxonomy filter

Shipped

provider_ingest streams the 9.6M-row CMS NPPES bulk file in ~1m50s, filters to the curated menopause NUCC taxonomies (OB/GYN, urogynecology, gyn-onc, repro endo, NP — Women's Health / Gerontology / Adult Health, CNM, FM, IM, etc.), unions an MSCP overlay (synthetic + self-reported), computes a graphScore, and emits a 2,015-row generated JSON. The committed national run captures 15 menopause-certified providers + 2,000 menopause-relevant non-certified providers spanning all 50 states + DC across 930 ZIP-3 prefixes — a coverage-aware selection round-robins the non-certified budget across prefixes (and the pipeline drops non-US/garbage postals), so far more ZIPs get a placeable local result.

Phase 2 — Distance, signals, sanctions, insurance, UI

Shipped

Five workstreams landed. Distance ranking (Census 2020 ZCTA centroids, Haversine, ranked within tier). Service-line signals (6 NPPES tokens: FACOG, FAAFP, WHNP, CNM, multi-taxonomy, etc.; 22% coverage). State sanctions (CA + NY + TX, 1,720 candidates dropped at build, license-keyed cross-walk via NPPES). Insurance overlay (synthetic-but-real-shaped, per-NPI, agent surfaces it provisionally). Patient-facing UI (/provider browseable index + /provider/<npi> profile pages with the full surface). The live MuleSoft worker DataWeave was rewritten to match the same Phase-2 contract; deploy is pending. FL / NJ sanction overlays are blocked by data access (auth-gated / PDF-only).

Phase 2-bis — Clinic-site detection + commercial insurance feed

Gated on need / partnership

Two pieces wait for an explicit need or external dependency: a clinic-website scraper for HRT / perimenopause / vasomotor service mentions (NPPES signals already cover the high-confidence cases — the scraper adds the remaining tail), and a paid in-network feed (Ribbon Health, Turquoise) that replaces the synthetic insurance derivation. Both swap in behind the existing contract without consumer changes; we don't ship the scraper today because brittle and we don't ship the partnership today because not yet purchased.

Phase 3 — Closed-loop scoring

After first ~1,000 referrals

Pull patient and provider outcomes from Pause's own data. Re-weight the scoring model. From here, the graph self-improves and competitors can't catch up by buying any single dataset — the moat is the referral history.