On November 7, CMS released a memo explaining what data Medicare Advantage carriers need to submit so that their directory information appears in the Medicare Advantage Plan Finder. This directory data will support beneficiaries’ plan discovery and selection workflows that consider providers’ in-network status (i.e., “help me find a Medicare Advantage plan that has my preferred providers in-network”). In our previous post, we explored the development phases and what MA carriers can do in preparation for CMS actions. The November 7 memo goes into more detail on specific dates and expectations, the technical options that MA plans must consider, and how CMS intends to evaluate and use the data. In this piece, we will summarize the requirements and provide commentary on what areas MA carriers should be paying the most attention to.
Here are the specifics on the timeline:
Phase 1 (CMS uses data from SunFire Matrix) CY2026 – This is where we are currently. CMS is using data collected by SunFire Matrix to populate provider directory data into MA Plan Finder (MPF). MA carriers currently not in the SunFire dataset can submit their data to Sunfire to ensure their networks are represented in MPF.
Phase 2 (MA Carriers submit data directly to CMS) CY2027 – This is the next phase where MA carriers submit data directly to CMS (i.e., making it publicly queryable and CMS queries it). There are intermediate milestones to review technical guidance, respond to the guidance, make URLs available, and test the APIs:
- Nov 7–Dec 19, 2025: Comment period
- Jan 16, 2026: Final guide
- Feb 2, 2026: HPMS URL fields live
- May–Aug 2026: Testing window
- Sept 1, 2026: Attestation due
- Oct 1, 2026: CY 2027 MPF launch
Phase 3 National Provider Directory (NPD) Future TBD – This is dependent on CMS’s future plans to implement NPD that will support multiple use cases that leverage directory data. When NPD is established, it will ingest data from payers’ Provider Directory APIs and then make data available to the MPF.
What are the requirements for MA plans?
Please consult with your API and PDM vendors to review CMS’s technical guidance in detail, but here’s the tl;dr of the technical guidance and the requirements that MA plans must be aware of:
MA plans need to publish directory data – CMS is making dual options available to MA carriers to meet this requirement. The first one is publishing directory data via FHIR APIs that were already required as part of CMS-0057-F Interoperability Final Rule starting in July 2021. The second option is to publish machine-readable files that are similar (although not exactly the same) as those they are currently publishing for ACA plans offered on the Healthcare.gov federal exchange. In both options, data must be updated at least every 30 days.
The data elements that are required to be in the API or Files include:
- NPI
- Provider Name (Type 1 Individual or Type 2 Organization)
- Provider Type
- Address
- Phone Number
- Specialty
- Languages
- Plans (inclusive of Provider-Plan relationship, PBP IDs, and plan year)
Publish API endpoints or JSON file location in HPMS system – This is how CMS will know where the files are located (and where to access the data). MA carriers will be required to keep the URL locations of either their API or files up-to-date in HPMS starting in February 2026. MA carriers and their technology teams can contact hpms@cms.hhs.gov to determine how to gain access to HPMS to submit these URLs.
Annual attestation of the data – A C-level official within the MA Carrier will need to annually attest (within HPMS) that the data submitted is ‘Accurate, complete, and truthful at the time of the attestation to the best information, knowledge, and belief of the MA organization.’
Conformance, monitoring, and consequences of non-conformance – Because CMS will begin using the data to populate MA Plan Finder, they are going to pay a lot more attention to payers’ directories and APIs. Here are the activities that CMS will perform proactively to scrutinize payer APIs:
- They expect to crawl each MA carriers’ file or API daily to ensure uptime and conformance
- CMS will validate the results and provide constructive feedback to the MA carriers
- MA carriers will be given an opportunity to resolve issues
- CMS reserves the right to suppress MA plans from the MA Plan Finder if the MA carrier fails to annually attest, if validation results produce errors, or if data quality issues exceed some CMS-set threshold.
As CMS tightens its requirements, starts using this data in MA Plan Finder, and rolls out automated checks, MA carriers should anticipate increased scrutiny and enforcement around their directory APIs/files and data quality.
Are MA plans ready for this?
The short answer is no. While payers have technically been required to publish functioning provider directory APIs since July 2021, which is more than four years ago, their implementations still fall short. Progress has been made: Defacto, for example, is integrated with 140+ payers’ APIs and machine-readable files covering more than 80% of U.S. covered lives. Defacto has provided constructive feedback to payers on their APIs or implemented workarounds to query. But CMS is far less forgiving than Defacto when evaluating the data coming from JSON files or FHIR endpoints, and most payers will not meet the new requirements in their current state. Below, we outline the top 10 checks payers need to make to ensure their APIs are ready.
In true Atul Gawande fashion (or Peter Pronovost, if you prefer), here is the checklist:
- Do you have an API? – Make sure you have an API, it is discoverable, and that it is clear the API belongs to your organization (a domain name shared with your member-facing website is a nice touch). List applicable contract years and contract numbers for each API. If you don’t know whether you have an API, ask your CIO, or ask your CIO to ask your API vendor, or ask Defacto.
- Does your API have all the data? – Support all required resources: Practitioner, PractitionerRole, Location, Organization, OrganizationAffiliation, Network, InsurancePlan. Avoid omitting linking resources (many of you chose to omit PractitionerRole and OrganizationAffiliation, or are missing Network references … CMS is not going to let that fly as that will fail their validation checks).
- Are you gating your API? – No authentication gateways, required account creation, or required API or file access credentials are allowed. I know that there’s debate on this in the plan community, as payer API teams want to know who’s hitting their APIs and to be able to restrict or rate-limit if querying becomes excessive. Defacto has been willing to work with payers to use client-specific credentials to query their APIs and will continue to do so, if payers require it and CMS does not restrict it. If CMS restricts it, payers who are seeing issues with over-querying should consider bulk publish (ACA-style json, or even bulk fhir publish) approaches rather than gating their APIs. More on this in #7 API Performance below.
- Does your API include Plan Details? – Most payers are not currently publishing explicit PBP IDs for their Insurance Plan resources and will need to add these identifiers to support CMS requirements. Other payers need to do a better job of including member-recognizable Insurance Plan names that are present in their own directories and member marketing material. (Aside: A standard Network ID published in all machine and human-readable artifacts about plans would solve this problem.) All of this will be required by CMS. Understandably, because otherwise MPF won’t be able to link the data appropriately!
- Does your API present Provider-Plan relationships? – For those payers who are currently non-compliant with the FHIR API requirement, this is the most prevalent issue. They’re often publishing provider (Practitioner and Organization) resources, but not linking them to Insurance Plans (either because they don’t have proper network linkages within Practitioner Role or Organization Affiliation, or they don’t have Practitioner Role or Organization Affiliation at all, or they don’t have Insurance Plan at all). Similar to #4, you need to get this right, otherwise the Provider-Plan relationships won’t be represented accurately in MPF when members search for plans that have their preferred providers. It is also the primary reason members visit your directory: to determine in-network status of providers. Your API should be able to handle that basic query question.
- Does your API have NPIs? – According to the Technical Guidance, NPIs will be required in the APIs. The NPI Final Rule was issued in 2004. Currently, NPIs are required for so many core transactions (claims, payments, eligibility inquiries, etc.). Your providers have NPIs. They need to be included. If you don’t, your API will not pass validation checks, and your network data will not populate MPF.
- Is your API performant? – CMS has said they are going to query your API daily. That could mean they want to query your entire network directory daily, or it could mean they are just doing a quick API uptime and conformance check. Most payers support millisecond API response times, and with most payers’ networks, that’s sufficient for multi-day querying. That might not be enough to support daily network-wide querying from CMS, however. For those payers with national networks (where querying can take multiple weeks or an entire month), you’re going to need to think of better approaches to make your data available to CMS daily. This might mean ACA-style json payloads or bulk fhir export / publish approaches. For those payers whose APIs take 5 seconds to respond and craps out with 503 errors after every 10th query, you’re going to need to build more performant APIs than what you currently have. We know that there are some ‘federated’ implementations of these APIs that are highly dependent on upstream APIs from leased networks, and that this type of architecture can affect performance. In that case, you will not only need to make sure your own APIs and databases are performant, but also your upstream data sources.
- Is your API consistent with your web directory? – CMS does not explicitly require real-time parity between API and web directory data (they recognize there are sometimes timing differences in updates across systems), but they do indicate they will be sensitive to data quality concerns. If data in your API doesn’t match your web directory for longer than a brief update window, that’s a problem. Beneficiaries are going to expect that the information they get from MPF is the same as your web directory.
- Does your API support basic query parameters? – CMS also doesn’t explicitly indicate which query parameters are required. Think of the basic ones though: search for Locations by city/state or zipcode, search for Practitioners by location, search for Practitioners participating in a specific plan, search for all Plans that a Practitioner accepts, search for Organization by location, search for the Plans an Organization accepts. If these query parameters are impossible because the resources aren’t even populated, or because your upstream data repos don’t model those relationships, those are things you are going to need to fix. Support pagination (these are the ‘next’ links in API results). We’ve noticed that when payers (and their API teams) see and acknowledge the pagination issue, it’s typically been a quick fix.
- Does your API support the logical data model prescribed by CMS? – Ensure all resources are properly linked to support machine-readable use cases, e.g., Practitioner ↔ Organization ↔ Network ↔ InsurancePlan. There’s a really good E-R diagram in the technical guidance. Make sure your data reflects all of these relationships. It’s the connections between these data that are important (you won’t be able to handle 2, 5, and 9 above without these logical connections)!
A few other closing remarks.
This is still draft technical guidance. You have until December 19, 2025 to respond to a CMS survey. Consider questions around the daily querying v. monthly update requirement, the role of bulk FHIR, and how and when CMS may expect to ingest the data directly into a National Provider Directory.
Many payers who were challenged since 2021 to get their Provider Directory APIs working realized that the root of their issues were upstream in their Provider Data Repository (or their realization that they had multiple, siloed, unmastered repositories). Make sure your upstream systems and your data models are ready to support this detailed, logically linked data that CMS is requiring. This is actually the long pole in the tent. Your API vendor will act on the above requirements if you make the right data available to them. If you’ve been putting off that big PDM migration, vendor selection, or consolidating all of those siloed MS Access databases, this is the time. The National Provider Directory itself, while it could finally be a source of truth for the industry, does not preclude your organization from having to master your data, especially about your networks, plans, and the providers who are associated with them. With the current timeline, you have ~6 months to complete this before testing starts.
CMS has not posted the technical guidance on its web site or on regulations.gov, but you can inquire about the technical guidance or the memo at hpms@cms.hhs.gov.