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

A great recipe for a better user experience.

Overview and Background

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

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

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

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

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

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

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

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

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

Key Concepts

  • 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?

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


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

So, how do we make this happen?

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

Are there any alias names that the app should add?

How many different member portals exist in your organization?

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

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.

Conceptual Data Model

You made it to the end.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store

OneRecord is a digital health company that empowers consumers to access, aggregate & share their healthcare data with the people & organizations that they trust