Network Mapping


The User Dropdown may not always be the preferred option for customers as it puts the onus of selecting the appropriate Ribbon network on the end user (whether this is a patient, clinician, referral coordinator, etc.). In these cases, you may choose to instead surface your members’ insurance plans within your UI and map these plans to the relevant Ribbon network UUIDs on the back end. This can be a non-trivial task, given insurance plan data is often formatted in a variety of different ways across insurance cards, plan documents, and payer websites.

Ribbon's insurance data, including the carrier and plan name, matches the formatting found on payer websites. Depending on the formatting of your users' plan information, you will likely need to map these insurances to Ribbon's UUIDs through a manual mapping process. We recommend mapping all available members' plans to Ribbon UUIDs before launching your product.

Map an insurance plan

To map a member's insurance plan to a Ribbon UUID, we recommend following the steps below. If you're still unable to map an insurance plan, please reach out to Ribbon at [email protected] and we can help identify the correct Ribbon Insurance plan.

Identify plan information

We recommend identifying and compiling all sources of plan information available, including plan documents and relevant networks. The more information you have available, the easier it will be to search for the correct Ribbon UUID in the /insurances reference endpoint.

At a baseline, Carrier and Plan Name are crucial to surface a relevant Ribbon Insurance plan.


You can use the /insurances reference endpoint to query insurance plans by available plan information. The search parameter to input the plan name and carrier_name parameter to input the relevant carrier. We also recommend using the plan_type and state parameter if you're having trouble narrowing down to a reasonable list of potential plans.


If you're able to identify the correct plan, that's great! You can now use the associated UUID as an input into future provider search requests.

If you're unable to find the correct plan (and Ribbon UUID) from querying the /insurances reference endpoint, there are a few steps you can take:

  • Modify the query parameters! Sometimes plan names have slight discrepancies or Ribbon can't correctly assign state to a plan due to carrier-level limitations. Broadening the search query and relaxing parameters can potentially help surface more relevant plans.
  • Reach out to Ribbon at [email protected] if you still can't find the correct UUID, and we can help you resolve some of your more difficult mappings.

Having trouble finding the right plans?

If you cannot find the correct insurance plan for a smaller carrier, Ribbon may not be collecting the plan. Reach out to [email protected] if this is the case and we can try to collect these new plans!


We recommend using the API to identify relevant Ribbon UUIDs. However, upon request, Ribbon is also able to share an updated list of all of the insurance networks available in your custom index for easy viewing of available network data.