Insurances Endpoint

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

FieldDescription
uuidRibbon unique identifier for the given insurance object.
carrier_associationName of the top level payer association (e.g. "BCBS Association").
carrier_brandName of the payer brand (e.g. "BCBS")
carrier_nameName of the functional / operating payer for the given plan (e.g. “Blue Cross Blue Shield of Illinois”).
stateTwo letter abbreviated state code (e.g. "NY").
plan_nameName of the plan (i.e. “BlueCare Direct”).
plan_typeType of plan (i.e. "PPO", "HMO", "POS").
display_nameCleaned single value combining carrier_name, plan_name, and plan_type.
categoryCategory or line of business of the insurance plan (e.g. "Group", "Medicare Advantage", "Federal Exchange").
codesInsurance 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:

ParameterExample ValueDescription
searchAetnaFuzzy search across the information in the display_name, carrier_name, and uuid fields.
uuid12403618-49d5-43ee-99ad-5e99194fe05cReturn the insurance object associated with a specific Ribbon insurance UUID.
carrier_associationBCBS AssociationReturn plans with an exact match for the carrier_association.
carrier_brandBCBSReturn plans with an exact match for the carrier_brand.
carrier_nameBlue Cross Blue Shield of IllinoisReturn plans with an exact match for the carrier_name.
stateNYTwo letter abbreviated state code input to return plans for that state.
plan_nameBlueCare DirectReturn plans with an exact match for the plan_name.
plan_typePPOReturn plans with an exact match for the plan_type.
display_nameBlue Cross Blue Shield of Illinois - BlueCare Direct - HMOReturn plans with an exact match for the display_name.
categoryMedicare AdvantageReturn plans within the category / line of business.
codesH9572-001Single code input to return plans with an exact match within the codes field.
partial_codesH9572Returns 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.