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=AetnaTo search across available plans in your custom index, your URL will include
custom, like this:
https://api.ribbonhealth.com/v1/custom/insurances?search=AetnaThe 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 6 months ago