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!

Search Parameters

You can search for insurances using the following parameters:

Parameter

Description

search

Fuzzy search across all information within an insurance object.

uuid

Ribbon unique identifier for the given insurance object.

carrier_brand

Name of the payer brand (i.e. “BCBS”).

carrier_name

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

state

Two letter abbreviated state code.

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 (i.e. Group, Medicare Advantage, Federal Exchange).

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 4 months ago