Five years ago, the first CMS Interoperability and Patient Access Final Rule (CMS-9115-F) required health insurers to publish Provider Directory APIs. These FHIR endpoints were intended to make provider network data openly available to members, developers, and anyone building tools to help people find care. The vision was straightforward: standardize the data, open the endpoint, and let innovators build workflows to address a variety of use cases.
The reality has been more complicated.
You have a Provider Directory API, but does it work?
Most large payers now have a Provider Directory API. Many compliance teams will even point to their API and confidently state, “Yes, we have a Provider Directory API. We are compliant.” Some even publish their Provider Directory APIs on the interoperability page on their website alongside their Patient Access API and their Transparency in Coverage files.
But “having an API” and “having a working API” are not the same thing. Developers who have tried to consume payer Provider Directory APIs at scale have encountered a familiar set of problems: Practitioner resources without NPIs, PractitionerRole resources with no networks, Location resources with just zipcodes and no street addresses, zero Organization resources, zero InsurancePlan resources, and in some cases, APIs that have zero resources at all.
This is not primarily a technical failure. The APIs themselves work fine. They have capability statements and the right set of resources. However, the data is unusable and cannot answer the simplest question that patients ask: “What providers are in-network for my plan?” This is a data pipeline failure. The problem lies upstream of the API, where it interfaces with payers’ other systems: either their Provider Data Management system or their Directory solution.
On Friday, May 1, 2026, CMS released technical guidance to payers on Medicare Plan Finder. The technical guidance is to satisfy CMS-4208-F2, a rule requiring Medicare Advantage organizations to make directory data available to CMS to be used in Medicare Plan Finder. The new guidance requires that payers take the FHIR resources they are producing for their API and make it available in FHIR-based JSON files.Â
This means that payers will be presenting data in two different delivery outputs, the FHIR API to satisfy CMS-9115 and the FHIR-based JSON file to satisfy CMS-4208-F2. Payers will need to source the right data and make it available in two different formats to comply with parallel regulatory requirements.
The Three-Part Problem of Provider Directory Endpoints
Functioning Provider Directory endpoints require three things to work together, and most implementations only solve one of them.
- Finding the right data. Health plans often maintain provider data across multiple source systems: credentialing platforms, claims adjudication systems, provider relations databases, and legacy directory tools. These systems often disagree. Before a single FHIR resource can be published, someone within the payer organization has to harmonize those conflicts and determine which system should be used to populate the Provider Directory endpoints.
- Transforming and mapping it correctly. The Da Vinci Plan-Net profile, the FHIR implementation guide that governs Provider Directory APIs, makes specific demands: how a provider’s network participation is expressed through PractitionerRole, how an OrganizationAffiliation references a Location, and how an InsurancePlan connects to a network that connects to providers. Mapping source data to these structures accurately requires both FHIR expertise and a deep understanding of the source data’s quirks and gaps. The upstream systems may loosely align with the Da Vinci logical model, but more often than not, judgement calls need to be made by professionals knowledgeable about the data domain.
- Keeping it current. A directory that was accurate at go-live and has not been updated since is not a compliant directory. CMS expects provider data to be refreshed at least every 30 days. For a plan with an active network enrollment pipeline — providers joining, leaving, changing locations, adding specialties — that means a continuous data operations function, not a one-time implementation project. Payers need to also manage the tricky period between Open Enrollment and the new year, bringing in both current plan-year and future plan-year data. This requires the proper use of period start and end ranges within Insurance Plan.
The API and Bulk FHIR output are at best one-third of the solution. The heavy lift is upstream and requires expert implementation, robust ETL guidelines, and plenty of integration experience.
CMS-9115’s Public Accessibility Question
There is one additional issue worth naming directly because it affects whether a Provider Directory endpoint is useful at all to the parties CMS most wants to reach.
CMS-9115 specifies that the Provider Directory API “must be accessible via a public-facing digital endpoint on the payer’s website to ensure public discovery and access.” CMS-4208-F2 further clarifies, in the context of the Medicare Plan Finder integration, that these APIs “may not require user authentication and authorization or any other protocols that restrict the availability of this information.”
Some payers have interpreted the original rule as permitting developer portal registration, API key requirements, or manual approval workflows before granting access. This interpretation has some support in CMS FAQ language for the CMS-9115 rule.
CMS, in their updated guidance for Medicare Plan Finder, has been clear that it expects the new FHIR-based JSON files to be publicly accessible and downloadable. Payers need to be sure that the URLs for those files are submitted to CMS and do not require any registration steps to access. As a best practice, the URLs should be published wherever they are publishing their other interoperability and price transparency URLs to comply with government requirements.
Plans preparing for the October 1, 2026 Plan Finder go-live date should confirm that their FHIR-based JSON files are reachable without authentication by any HTTP client because that is the easiest way for CMS to reach it, provide constructive feedback on the data, and to ensure that payers’ Medicare Advantage (MA) products appear on Medicare Plan Finder.
What Good Looks Like for a Payer’s Provider Directory Endpoints
A well-implemented Provider Directory API and FHIR-based JSON files have a few observable characteristics that distinguish them from a checkbox implementation:
- Every PractitionerRole resource links to a real Practitioner, a real Organization, and at least one Location with a valid address.
- InsurancePlan resources carry the plan-level identifiers (contract-plan-segment IDs) needed to trace network participation to a specific, enumerated MA product.
- PractitionerRole and OrganizationAffiliation resources reference networks that are themselves referenced by InsurancePlans. This ensures that the most important question is answered, “What providers are in-network for my plan?”
- The data includes meaningful results for real-world questions — provider search by location, specialty lookup, and network participation confirmation.
- Data is refreshed at least monthly, and both current and future plan-years are presented side-by-side during the Open Enrollment period.
As the Plan Finder deadline approaches, payers that built their APIs in 2020 and have not revisited them since may find that the implementation they have is not the one they need.
The Moment of Accountability for Payers
CMS-4208-F2 creates something that CMS-9115 largely lacked: a concrete, consumer-visible consequence for poor directory data. If a plan’s provider directory does not pass CMS validation, that plan may not appear in Medicare Plan Finder during the Annual Enrollment Period. For Medicare Advantage plans, this can negatively impact enrollment and revenue.
That consequence changes the conversation internally. Compliance teams need to ask tougher questions about whether their APIs and files are compliant. The question is whether the data flowing through the endpoint is accurate, complete, current, and downloadable or queryable. The APIs and files must be usable by CMS and other third-parties, or else the payer’s MA products may become invisible.
1upHealth Turns Provider Directory Compliance into a Strategic Advantage
As part of their work enabling secure and compliant health data exchange, 1upHealth has been partnering with health plans on Provider Directory APIs since CMS-9115-F — and that work continues with CMS-4208-F2. 1upHealth is now working with its customers to transform these endpoints from compliance checkboxes into genuine market advantages, because showing up fully and accurately in Medicare Plan Finder is a competitive differentiator, not just a regulatory obligation.
That work begins with a gap analysis of the data available via current provider directory APIs: assessing required FHIR resources, key relationships (e.g., provider -> network -> plan), and where critical data elements are missing or misaligned to identify exactly where implementations fall short. From there, 1upHealth works with payer IT and provider data teams to define mapping strategies aligned to Da Vinci Plan-Net and establish the data pipelines needed to support accurate, queryable APIs.
In practice, this has included helping plans identify missing or partially ingested data, address gaps in provider-to-network-to-plan relationships, and rework upstream data structures so their APIs return meaningful results for real-world queries.
This work also requires recurring data ingestion and refresh processes (e.g., monthly full file submissions) to meet CMS expectations, reinforcing that Provider Directory readiness is an ongoing data management effort, not a one-time implementation.
Finally, 1upHealth believes that when rules shift, as they did on May 1st when CMS released a revised technical guide requiring a FHIR bulk publish operation, health plans should not have to scramble to keep up. 1upHealth is working to incorporate these changes into its implementations, ensuring health plan customers remain on track for the October 1, 2026 Plan Finder go-live.
Interested in learning more about Defacto Health’s work? Visit https://defacto.health/.
Ron Urwongse is co-founder of Defacto Health, which aggregates and scores provider-insurance relationship data from payers’ Provider Directory APIs and machine-readable files. Defacto works with technology vendors, health plans, and other organizations to power workflows and analytics with provider network data. Views expressed are the author’s own.
