GuidesDiscussionsTry Ribbon!

Insurances Endpoint

Suggest Edits

Overview

Description: This endpoint allows you to search through insurances that exist within the Ribbon API.

If you are leveraging a Custom Provider Index, then you can also use this endpoint to create and edit your own insurances.

Endpoints:
Standard Index: /v1/insurances/ and /v1/insurances/{UUID}
Custom Index: /v1/custom/insurances/ and /v1/custom/insurances/{UUID}

Status: Live

Methods:
Standard Index: GET
Custom Index: GET, PUT, POST, DELETE

Example use-case:
You want your users to be able to select from a drop down list of available insurances, which you power through GET requests to this endpoint.

If you have a custom index, you may also want to add an accepted insurance to a provider that does not yet exist -- so you create a new insurance through the POST method.

Diving In - Searching & Viewing Insurances

To search across the insurances endpoint, you can use GET requests.

Add the "search" parameter to get a paginated list of all available insurances. This parameter will run a 'fuzzy' search against key fields within each insurance object to return the most relevant options.

For example, if you are looking for Aetna insurances, you could conduct a call as follows:

curl -X GET \
  'https://api.ribbonhealth.com/v1/custom/insurances?search=Aetna' \
  -H 'authorization: Token <your_token>'

The response to the GET request above is a list of relevant plans (i.e. that contain "Aetna") along with the total count of returned results ("count"):

{
    "count": 452,
    "next": "http://api.ribbonhealth.com/v1/custom/insurances?search=aetna&page=2",
    "previous": null,
    "results": [
        {
            "uuid": "12403618-49d5-43ee-99ad-5e99194fe05c",
            "carrier_association": "Aetna",
            "carrier_brand": "Aetna",
            "carrier_name": "Aetna",
            "state": "TN",
            "plan_name": "Aetna Whole Health",
            "plan_type": "",
            "metal_level": "",
            "display_name": "Aetna - TN - Aetna Whole Health",
            "network": "",
            "confidence": 4
        },
        {
            "uuid": "5a456d15-0fdd-4418-a149-b13ebe2e3738",
            "carrier_association": "Aetna",
            "carrier_brand": "Aetna",
            "carrier_name": "Aetna",
            "state": "NY",
            "plan_name": "Aetna Whole Health - Metro NY",
            "plan_type": "",
            "metal_level": "",
            "display_name": "Aetna - NY - Aetna Whole Health - Metro NY",
            "network": "",
            "confidence": 4
        },
      ... 478 more insurances ...
      ]
}

🚧

Searching for insurances can be done in Ribbon's standard index or your 'custom index'

To search across available plans on a standard index, your URL will look something like this:
https://api.ribbonhealth.com/v1/insurances?search=Aetna

To search across available plans in your custom index, your URL will include custom, like this:
https://api.ribbonhealth.com/v1/custom/insurances?search=Aetna

The results will be the same unless you have added, edited, or deleted any insurance plans from your custom index.

❗️

The sections below are only relevant if you are using a 'custom index'

If you are unsure or would like to switch to a custom index, please reach out to the Ribbon team!

Insurance Data Fields

Field

Description

uuid

Ribbon unique identifier for the given insurance object.

carrier_association

Name of the top level payer association (e.g. "BCBS Association").

carrier_brand

Name of the payer brand (e.g. "BCBS")

carrier_name

Name of the functional / operating payer for the given plan (e.g. “Blue Cross Blue Shield of Illinois”).

state

Two letter abbreviated state code (e.g. "NY").

plan_name

Name of the plan (i.e. “BlueCare Direct”).

plan_type

Type of plan (i.e. "PPO", "HMO", "POS").

display_name

Cleaned single value combining carrier_name, plan_name, and plan_type.

category

Category or line of business of the insurance plan (e.g. "Group", "Medicare Advantage", "Federal Exchange").

codes

Insurance code associated with a plan. Ribbon currently supports PBP codes for Medicare Advantage plans, and HIOS codes for State and Federal Exchange plans.

Search Parameters

You can search for insurances using the following parameters:

Parameter

Example Value

Description

search

Aetna

Fuzzy search across the information in the display_name, carrier_name, and uuid fields.

uuid

12403618-49d5-43ee-99ad-5e99194fe05c

Return the insurance object associated with a specific Ribbon insurance UUID.

carrier_association

BCBS Association

Return plans with an exact match for the carrier_association.

carrier_brand

BCBS

Return plans with an exact match for the carrier_brand.

carrier_name

Blue Cross Blue Shield of Illinois

Return plans with an exact match for the carrier_name.

state

NY

Two letter abbreviated state code input to return plans for that state.

plan_name

BlueCare Direct

Return plans with an exact match for the plan_name.

plan_type

PPO

Return plans with an exact match for the plan_type.

display_name

Blue Cross Blue Shield of Illinois - BlueCare Direct - HMO

Return plans with an exact match for the display_name.

category

Medicare Advantage

Return plans within the category / line of business.

codes

H9572-001

Single code input to return plans with an exact match within the codes field.

partial_codes

H9572

Returns plans with a partial string match to the codes field.

For Medicare Advantage plans this is a contract ID (i.e. H9572). For Federal or State Exchange plans this is the first 10 digits of the HIOS ID (i.e. 36096il100)

This parameter can only be used if the category param is also utilized

Diving In - Creating New Insurances

If after sifting through the available insurances, we cannot find our plan anywhere, then we should create a new one! Let's say that the Aetna plan we want to add is New Happy Plan.

We can do this by making a POST request as follows:

curl -X POST \
  'https://api.ribbonhealth.com/v1/custom/insurances' \
  -H 'authorization: Token <your_token>'
  -D '{
            "carrier_association": "Aetna",
            "carrier_brand": "Aetna",
            "carrier_name": "Aetna",
            "state": "",
            "plan_name": "New Happy Plan",
            "plan_type": "",
            "metal_level": "",
            "display_name": "Aetna - New Happy Plan",
            "network": "",
            "confidence": 4
}'

Pending a successful response, we'll get a new UUID we can use to add to doctors:

{
  "data":{
            "uuid": "12403618-49d5-43ee-99ad-5e99194fe05c",
            "carrier_association": "Aetna",
            "carrier_brand": "Aetna",
            "carrier_name": "Aetna",
            "state": "",
            "plan_name": "New Happy Plan",
            "plan_type": "",
            "metal_level": "",
            "display_name": "Aetna - New Happy Plan",
            "network": "",
            "confidence": 4
    }
}

🚧

New feature in API Version [2021-05-13]

We have released a new feature that introduces data type validation to stock Ribbon Fields in API Version [2021-05-13]. This validation applies when you create new insurances.

For more information, please refer to this changelog.

Diving In - Editing & Deleting Insurances

Now, what if we need to delete or edit this insurance?

With the /v1/custom/insurances/{UUID} endpoint, we have two methods: DELETE and PUT.

A PUT request allows you to edit an insurance you created.

A DELETE request allows you to delete the inputted insurance's UUID.

Let's say that we realize we messed up the new plan we created, and instead of being called New Happy Plan, the plan is really called Not So Happy Plan. We can edit like so:

curl -X PUT \
  'https://api.ribbonhealth.com/v1/custom/insurances/20c26c1e-0ac3-44b8-b798-e09427a0de78' \
  -H 'authorization: Token <your_token>'
  -d '{
            "carrier_association": "Aetna",
            "carrier_brand": "Aetna",
            "carrier_name": "Aetna",
            "state": "",
            "plan_name": "New Happy Plan",
            "plan_type": "",
            "metal_level": "",
            "display_name": "Aetna - Not So Happy Plan",
            "network": "",
            "confidence": 4
}'

This will maintain the same UUID for this insurance, so the edit will be reflected across all providers who are associated with this plan.

👍

You can edit and delete custom made insurances as well as Ribbon created insurances

You can edit or delete the insurances that Ribbon provides as well as custom insurances you have created.

Now, what if we want to delete this insurance? Easy! We just make a DELETE request to this endpoint, as shown below:

curl -X DELETE \
  'https://api.ribbonhealth.com/v1/custom/insurances/20c26c1e-0ac3-44b8-b798-e09427a0de78' \
  -H 'authorization: Token <your_token>'

🚧

New feature in API Version [2021-05-13]

We have released a new feature that introduces data type validation to stock Ribbon Fields in API Version [2021-05-13]. This validation applies when you edit insurances.

For more information, please refer to this changelog.

❗️

Be careful when deleting a custom insurance!

If you've added this insurance to a many doctors and then delete it, you are completely deleting all instances of this UUID, and we will not be able to regenerate them.

Updated about 2 months ago