The 3 Must-Have Ingredients to a FHIR Health Plan Directory

14 min readMay 19, 2021


A great recipe for a better user experience.

Overview and Background

Third-Party Applications, such as OneRecord, are helping members connect to records maintained by their health plan. In order to access their records, members need to authenticate with their health plan and authorize the third-party application to access and retrieve those records on the member’s behalf.

Directing the member to the correct authentication screen from within a third-party application is a key component of this workflow. Members will search for their health plan through an application’s search functionality to find their health plan.

In order to achieve an ideal consumer experience, we suggest that payers create and maintain a health plan directory to complement their FHIR API. While a spreadsheet or other type of file containing the information is certainly helpful, a maintained directory, available via an API, that could be accessed by the third-party applications is a “MUST” to build the best consumer experience (hint, hint).

Key Players

There are several important actors involved in meeting the Interoperability and Patient Access final rule (CMS-9115-F) that are important to understand.

The member is the person that holds the health plan. They may have additional family members on their plan. They may also have multiple plans. For the purpose of comparison, the member is equivalent to the patient in clinical scenarios, and may often be referred to in this paper (and others) as one in the same.

The payer is the organization that provides the health plan coverage to the member. Payers will typically negotiate contracted rates with health systems creating a three-way relationship between the member, the healthcare provider, and the payer organization.

The third-party application sometimes referred to as “app” or “apps”, is an untethered software application that the member uses to access and aggregate their health information via a FHIR API. While the user experience in these apps will vary widely across the industry, the core actions of each third-party application are typically similar.

The member portal is the tethered software application and acts as the authorization server that the payer organization provides to members so they can authenticate and authorize to access their data. The FHIR servers are where the actual member data is made available. The FHIR servers will typically be an interface on top of an underlying database, but this is not a strict requirement and architectures will vary across the industry.

The Problem

Sharing non-electronic data with members is not new for payers. Sharing data electronically with third-party applications, like OneRecord, in a FHIR format is new. Payers have been working hard to build their Patient Access APIs and standing up FHIR servers but now the industry needs to go a step further to help members discover those APIs.

As part of the CMS Patient Access final rule, payers are required to enable access to healthcare data using the SMART on FHIR authorization standard. In order for a third-party application to authorize against a payer database, it must first know how to find the member portal or authorization server that ultimately grants access to that database. Following this discovery activity, the third-party application must be properly configured to connect to the authorization and FHIR servers to finish the remainder of the flow.

In addition to understanding what needs to be configured and how to configure it, third-party applications must also implement their flows in a way where the member has a successful user experience to access their data.

Understanding the structure of many payer organizations can be complicated — and members do not have time to sort through this, nor should they be responsible to figure it out. Having an easier way to search for the member portal information through a health plan directory, and enabling the successful completion of member data retrieval, is a key aspect of effective member engagement and compliance with federal regulation.

The User Experience

Speaking as a member who is using a third-party application to retrieve and store information related to my healthcare, I am presented with a search field in an application that I can use to find the place where my records exist. In the case of health insurers, I will type the name for my insurance with which I am most familiar. This will likely be the name on my insurance card, or the name of the company to whom I make out the check for my premium each month. Moreover, the member may even attempt to search on group ID for employee health plans, leading to further complexities in how the user experience needs to be constructed.

The third-party application needs to know these consumer-friendly terms and make those available in the search results. However, the app also needs to know how to collect and configure those consumer-friendly terms so that the app can direct the member to the appropriate portal for authentication and authorization AND where to route the API calls for connecting to the FHIR server.

For some payers, this user flow may be simple. Members will access a single portal address for authorization (OAuth2) that grants the member access to the FHIR server. The portal is located by using a single consumer-friendly term that is familiar to all members.

For other payers, there may exist multiple-member portals that align to the company/brand or product that the member purchased. After the member is authorized they then connect to a single FHIR server to retrieve their data.

Still, other payers may have a more complex configuration. For example, there is a portal for each brand in the organization, maybe even down to the plan level, and there is also a different FHIR endpoint URL for each corresponding portal.

Let’s Dive In Deeper

We’re about to get technical… if you haven’t had your coffee, you should probably skip to the next section.

Now that we have a general understanding of the challenge and what the ideal user experience should be, let’s lay out the problem areas more specifically. There are four key areas across which the challenges exist. The first three of these: Branding and Search, Authorization Servers, and FHIR Servers have a direct impact on the user experience and flow; the fourth involves operational aspects and change management.

Branding and Search

The user experience falls along a few different lines when it comes to a member being able to engage with their health plan data. The first of these is understanding what exactly to search for. Likely the member will reference their insurance plan card and search on what is printed there. Whether or not a result will be delivered to that member performing the search will highly depend on how the search feature of the third-party application is configured.

Each third-party application is responsible for providing a user experience and flows to connect the members to the authorization portal they will need to login into. If the third-party application does not understand what the payer organization structure is in regards to their parent and subsidiary organizations, brands, and individual health plans, then the third-party application will be challenged to provide a successful search experience for the member.

Another item to consider is search aliases. Each payer organization and its subsidiaries may have a number of additional names, oftentimes acronyms, that those organizations are also known as. One example is Blue Cross Blue Shield which has a very commonly known acronym of “BCBS.” An additional example, Kaiser Permanente, offers a variety of plans based on a specific line of business (or employer that offers the plan). Because of the many specific options, Kaiser Permanente (“KP”) offers, the terms most familiar to those members will vary greatly across settings.

While there are a handful of well-known aliases, those aliases may only be known to those of us in the industry, and not necessarily to the health plan member. Other aliases also exist, and if third-party applications do not have an understanding of these aliases to configure in their user experience then the member may be unable to quickly or efficiently find their health plan member portal upon searching.

Authorization Servers

Authorization Servers are also known as “member portals.” These are the web applications that present the user with a login screen and perform the authentication and the authorization for the member. Authentication is the process of validating who is accessing the system based on a provided username and password. Authorization is granting the appropriate level of access to that authenticated user. The two

concepts work hand in hand and are well understood in the IT industry. In the CMS Patient Access API, both the OpenID Connect Protocol and the SMART App Launch Framework are referenced which handle both the authentication and authorization layers and are built on the OAuth2 Authorization Framework.

Payer organizations may have a single authorization server or may have multiple. These could be aligned to lines of business (LOB) that the payer organization provides services for. For example, a payer organization could have one member portal for Medicare Advantage plans, one member portal for Medicaid plans, and one member portal for commercial insurance. Alternatively, a payer may have a single-member portal experience for all of their LOBs. However these authorization servers are implemented by the payer, third-party applications will need to understand these implementations so that proper configuration can be in place to enable members to connect, authenticate, and authorize successfully.

An additional challenge with the authentication and authorization layer is found in the varying SMART App Launch implementations across the industry. The SMART App framework was intentionally designed to support these sorts of variations because an overly prescriptive approach would result in a significant lack of adoption. The variations are not egregious in nature — they are just different ways that vendors have chosen to implement.

Today, third-party applications are able to use events such as HL7 FHIR Connectathons and CARIN Connectathons to vet out these variations. Without these testing events, as well as additional ways to collect this needed configuration information, third-party applications will be challenged to authenticate and authorize in production environments in a plug-and-play fashion.

What the industry needs is the yellow pages of healthcare. The question is: Will TEFCA be the answer to building the network of networks with a national health plan directory? **cough cough** We’re waiting!

FHIR Servers

Similar to authorization servers, FHIR servers may exist as a single gateway implementation or may exist as separate individual servers. There is no requirement in the CMS Patient Access API or in the recommended underlying implementation guides to have a single gateway, although this seems to be the general industry consensus as the right sort of implementation. Due to this, we fully expect to see a variety of implementations across payer organizations (oh no!). Similar to mentioned previously, this does not necessarily mean that one payer has a “good” implementation and another payer has a “bad” implementation — they are just different. However, if you ask our CEO she would tell you there are bad implementations because they increase the barrier of entry for third-party applications from an operational perspective.

Continuing on, it is quite possible there are good reasons for having multiple FHIR servers — such as supporting multiple LOBs. If third-party applications are not aware of the FHIR server implementation architecture, a seamless user experience will be challenging to create for members resulting in a negative overall outcome where members are not able to find their data as they expect.

Staying Current

Aside from the concepts discussed so far, the ongoing operational and change management aspect of payer organizations and their subsidiaries is important to understand so that third-party applications will have ample time to adjust and adapt to those changes.

Payer organizations may experience an entity-level change such as a merger and acquisition that can greatly impact any sort of relationship that has been established between third-party applications and those payers. While the technology implementation itself may not change (or at least not change immediately), the surrounding components of technology integration may change, namely the support channels.

In addition to such entity-level changes, a payer organization may choose to change technology vendors, clearinghouse vendors, or enact changes to their internal technology team and implementation. Such changes may include migration to a newer version of an integration framework or upgrading to a more recent version of HL7 FHIR. Payer organizations will also be constantly considering what internal organizational changes can be implemented (i.e., team restructuring) that may have an impact on what third-party applications experience could be with that payer. Whatever the trigger, third-party applications need to be more aware of these changes so they can act appropriately to enable members to have continued and uninterrupted access to their health plan data.

There is no requirement in the CMS Interoperability and Patient Access final rule for payers or their subsidiaries to provide notifications of any of these sorts of changes (womp, womp).

Payer Models

Knowing what information needs to be provided to third-party applications starts with understanding how payer organizations are structured. Continue reading to learn how we use the key concepts we covered earlier to illustrate common payer organizational models that we love to see in health plan directory.

Key Concepts

The key concepts we use to make this assessment are the same as what we’ve covered earlier: Brand, Authorization Server, and FHIR server.

  • The Brand is the recognizable term (or terms) that the member will find on their insurance card. Each payer may have a single brand or multiple brands.
  • The Authorization Server is the endpoint at which the member portal (or portals) resides. It redirects the member to/from the third-party application in order to authenticate and authorize the third-party application and pull records on the member’s behalf.
  • The FHIR Server is the location where the data is able to be pulled from. It does not necessarily represent the source of record of the data; it is more likely an interface between the source data and the requester (i.e., third-party application).

For a third-party application, the simplest payer model is to have a single Brand, a single Authorization Server, and a single FHIR Server. This configuration is resoundingly easy for the third-party application (with an exception of still needing to handle any specific authorization requirements the server places on top of the SMART App Launch Framework).

The other extreme is a payer has multiple Brands, multiple Authorization Servers, and multiple FHIR Servers. A many-to-many-to-many relationship creates a great deal more complexity that will need to be managed in third-party applications.

Want to see a visual?

The tables below illustrate what we believe to be the current variety of this Brand-Authorization-FHIR model for any given payer organization in the industry today.

It is important to also understand that the connectors between the circles in the various diagrams do not necessarily represent explicit transactional flows, rather they represent the conceptual relationship between the Brand, the Authorization Server, and FHIR Server.

Each of the payer model permutations listed is categorized into tables for the levels of complexity that we believe each represents. The first table provides the model with the lowest complexity, the second table represents models with medium complexity, and the last table has the highest complexity models.

Payer Brand-Authorization-FHIR Permutations

Payer Organizational Structures: LOW Complexity

Payer Organizational Structures: MEDIUM Complexity

Payer Organizational Structures: HIGH Complexity


We propose payers adopt our idea of a Health Plan Directory for Consumer Apps. This will enable third-party applications, which have a relationship with one or more payer organizations, to obtain information that will be used in guiding members to their data. This collection of data will help create the best member experience in third-party applications which will result in a return on investment (ROI) for payers as they navigate these new engagement models brought on by the 21st Century Cures Act.

For example, the Veteran Administration’s (VA) FHIR API is just one URL but they provide a Facilities API that enables third-party applications to populate all VA facilities within their UI. The consumer can then select the VA facility where they receive care. To the consumer, the member experience is akin to using a search engine on the web. This ensures that the consumers are able to easily navigate the application.

The initial implementation of the Health Plan Directory can be simple: a Github repository or a wiki page, which can later evolve into an API based solution. As an industry, the information that we collect and the lessons that we learn through this process of building this Health Plan Directory are very valuable. We can fold this information into future versions of health IT standards. This will provide significant benefit to the industry at large by eliminating major gaps that exist today between the healthcare IT standards and real-world implementations.

Alignment with CMS

The concepts laid out in this paper strongly align with the intent put forth in the CMS’s Interoperability and Patient Access Fact Sheet around providing a user-friendly and intuitive solution. Having a Health Plan Directory available will encourage innovation by allowing third-party application developers to access information to create a frictionless member experience.

So, how do we make this happen?

We need you to help make this happen. As part of the data collection process, we have created a proposed list of data elements to collect. This list is not intended to be exhaustive or to provide a full and complete understanding of each payer organization. Rather it is intended to collect the most relevant information within the scope of what is presented in this paper. This list is also expected to be updated over time as lessons learned are incorporated.

How many different insurance company names are listed on the insurance cards your organization issues?

When people search for their insurance within a third-party application, they are going to type the name that is printed on their insurance card. The app needs to know each of those names so they can have them listed and people can find what they are looking for.

Are there any alias names that the app should add?

If the insurance company typically goes by an acronym or abbreviated name, the app needs to know that. Or maybe the insurance company recently went through a merger and some members would continue to use the ‘old name’ to refer to the company.

How many different member portals exist in your organization?

This information tells third-party applications how many different auth servers they will need to direct members to/for authentication and authorization for the app to pull data on the member’s behalf.

How are the company names you listed related to the member portals?

The app needs to know the relationship between the two pieces of information so that the app can get the member to the right place to authenticate.

For each of the company names listed, tell the app the FHIR server for which the app should connect to retrieve the member’s records.

Once the app has gotten the member to and through the authentication process, the app will have the access needed for pulling the data the member requested. The app just needs to know where to make the call using the authorization granted by the member.

Conceptual Data Model

You made it to the end.

Congratulations. We appreciate you reading. Your feedback is warmly welcome — drop us a line at