By Mark Scrimshire, Chief Interoperability Officer, Onyx
The days of static provider directories are numbered. CMS is building a National Provider Directory powered by FHIR-based APIs, and starting October 1, 2026, the Medicare Plan Finder will begin ingesting provider and facility data directly from Medicare Advantage plans’ publicly accessible Plan-Net APIs. If your API isn’t ready, your plan data won’t show up — and your members will notice.
What CMS Is Doing and Why It Matters
Under final rule CMS-4208-F2, CMS is transitioning the Medicare Plan Finder from its current interim data source (SunFire Matrix, Inc.) to a model where CMS crawls MA plan Provider Directory APIs daily. This is Phase Two of a three-phase rollout that culminates in a full National Provider Directory.
The intent is straightforward: give Medicare beneficiaries accurate, up-to-date information about which providers are in-network for which plans. The mechanism is anything but simple. CMS will run automated scrapers across every registered MA plan’s FHIR API, pulling all seven required Plan-Net resource types, cross-referencing providers to plans via network linkages, and surfacing the results to consumers in Medicare Plan Finder.
This isn’t optional. Plans that fail to deliver compliant, performant APIs risk data suppression from Plan Finder entirely.
The Timeline Is Tight
Here’s what MA plans need to know:
February 2026 — HPMS opened API URL data entry fields for MA plans to register their provider directory endpoints.
February 18, 2026 — CMS published final technical implementation guidance for the Medicare Plan Finder MA provider directory requirements.
May 4 – August 31, 2026 — CY 2027 plan testing period. CMS will begin daily validation against registered API endpoints in the testing environment.
September 1, 2026 — Attestation deadline. MA organizations must confirm in HPMS that their provider directory data is accurate and complete for CY 2027.
September 18, 2026 — Production-ready provider directory API data must be live.
October 1, 2026 — Go-live. CMS begins relying on Plan-Net APIs to populate provider network data in Medicare Plan Finder for plan year 2027.
January 1, 2027 — Full compliance deadline for CMS-0057-F, which mandates Patient Access, Provider Access, Payer-to-Payer, and Prior Authorization FHIR APIs in addition to provider directories.
With testing beginning in May 2026, payers effectively have weeks — not months — to get their APIs into shape.
What CMS Actually Expects from Your API
CMS’s technical requirements go well beyond “stand up a FHIR endpoint.” Based on the published guidance and feedback from organizations already testing against the specification, here’s what CMS expects:
Open, unauthenticated access. CMS does not allow APIs that require registration or credentials. If your endpoint returns a 401, that’s not a bug report — it’s a compliance failure.
All seven Plan-Net resource types present and populated. InsurancePlan, Organization (Network), Organization (Facility), OrganizationAffiliation, PractitionerRole, Practitioner, and Location. Missing even one resource type means incomplete data in Plan Finder.
Open query support. CMS plans to query resources without provider names, locations, or other search parameters. If your API requires mandatory search parameters and rejects bare queries, CMS can’t scrape it.
Valid pagination. Large result sets must include working next links with consistent base URLs. Broken pagination means CMS only gets the first page of your data.
Daily query readiness. CMS intends to crawl APIs daily. That means response times need to be practical — endpoints taking 10+ seconds per request are not viable for bulk daily ingestion of hundreds of thousands of resources.
Referential integrity. This is where many implementations fall short. PractitionerRole resources must reference Practitioners that actually exist. OrganizationAffiliations must reference real Organizations and Locations. Most critically, there must be common Network references linking PractitionerRole and InsurancePlan resources. Without that linkage, CMS cannot determine which providers are in-network for which plans — rendering the entire directory effectively useless for Plan Finder’s core purpose.
Valid identifiers and codes. NPIs must pass Luhn checksum validation. NUCC taxonomy codes must conform to the standard format. MA Plan IDs must follow the H9999-001-001 pattern. CMS is running a single automated scraper across all APIs — there’s no room for format inconsistencies.
The Hidden Complexity: It’s Not Just About Having Data
The most common misconception we see is that standing up a FHIR server and loading data constitutes compliance. In practice, the hardest challenges are structural.
Consider network linkage — the connection between providers and insurance plans. A PractitionerRole resource references a Network. An InsurancePlan resource also references a Network. For CMS to determine that a provider is in-network for a given plan, those Network references must overlap. If they don’t, the result is effectively zero in-network providers for any plan, even if the API contains hundreds of thousands of provider records.
We’ve seen this exact scenario in real-world assessments. A major payer’s API returned 277,000 PractitionerRole resources, 13 InsurancePlans, and all seven resource types — but scored only 50% on readiness because of referential integrity gaps and data currency issues (only 2% of resources updated within the assessment window).
Introducing the Onyx Plan Finder Readiness Check
To help payers understand exactly where they stand, we built the Plan Finder Readiness Check — a free, browser-based tool that validates your Plan-Net API against the same criteria CMS will use.
Point it at your Plan-Net endpoint, and in minutes you’ll get a comprehensive assessment covering:
Resource presence and completeness — Are all seven required resource types available? Are required fields populated across your data, not just in a handful of sample records?
Field-level validation — NPI checksum verification, NUCC taxonomy format validation, MA Plan ID pattern matching, address completeness, and more — applied across sampled resources from each type.
Referential integrity — Does the PractitionerRole actually reference a Practitioner that exists? Are there orphan resources that nothing links to? And the critical test: do your PractitionerRole and InsurancePlan resources share common Network references?
API behavior — Can CMS query your API without authentication? Without mandatory search parameters? Do your pagination links actually work? Are response times practical for daily bulk ingestion?
Data currency — How recently was your data updated? CMS expects current data. If your resources haven’t been touched in months, that’s a red flag.
The tool generates an executive summary with a compliance score and detailed findings you can hand directly to your implementation team.
How Onyx Gets You to Compliant in One Week
Identifying gaps is step one. Closing them is where Onyx comes in.
Onyx has built proprietary ingestion guides and automated cloud deployment capabilities specifically for the Da Vinci Plan-Net implementation guide. Our approach eliminates the months-long implementation cycles that typically plague FHIR API deployments.
Proprietary data ingestion guides map your existing provider directory data — whatever format it’s in — to the Plan-Net FHIR resource model. We’ve already solved the mapping puzzles for the seven resource types, including the referential integrity requirements that trip up most implementations.
Automated cloud deployment provisions a fully configured, compliant Plan-Net API in your cloud environment. Not a prototype. A production-ready API with proper pagination, open query support, performant response times, and correct resource linkages.
One week to compliant. From raw provider directory data to a live, CMS-ready Plan-Net API. That’s not a marketing number — it’s what our tooling and experience make feasible. With the May 2026 testing window approaching, that speed matters.
The Bigger Picture: This Is Just the Beginning
The Medicare Plan Finder’s use of Plan-Net APIs is the leading edge of a broader CMS interoperability mandate. CMS-0057-F requires four additional FHIR APIs by January 1, 2027. The National Provider Directory initiative will expand beyond Medicare Advantage. The expectation that payers expose standardized, machine-readable data via open APIs is becoming the baseline, not the exception.
Payers who invest in getting Plan-Net right now aren’t just checking a compliance box — they’re building the foundation for every FHIR API mandate that follows.
Check Your Readiness Today
Don’t wait for CMS to tell you your API isn’t ready during the May testing window. Run the Plan Finder Readiness Check now, understand your gaps, and reach out to Onyx to close them before the clock runs out.