List and Create Insurances

Overview

Description: This endpoint allows you to search through insurances that exist in the Ribbon API, including the ones you have created, as well as to create your own insurances.

Endpoints: /v1/custom/insurances and /v1/custom/insurances/{UUID}

Status: Live

Methods: GET,PUT,POST, DELETE

Example use-case: You want to add an accepted insurance to a provider, but it does not yet exist -- so you create a new insurance through the POST method.

Diving In - Viewing & Creating Insurances

For the /v1/custom/insurances endpoint, you can make either GET or POST requests.

We make a GET request to get a paginated list of all the insurances available.

We make a POST request to create a new insurance if we do not see the one we are looking for yet.

An example of a standard request, looking for Aetna insurances, would be as follows (notice that search is set to Aetna):

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

We'll see that we'll get a list of all the insurances that have Aetna in any of their fields:

{
    "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 ...
      ]
}

After sifting through these insurances we cannot find our plan anywhere. Looks like we need to 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
    }
}

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/12403618-49d5-43ee-99ad-5e99194fe05c' \
  -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 only edit and delete custom insurances

You cannot edit or delete the insurances that Ribbon provides (although you can remove insurances from a provider record). If you want to 'edit' an insurance, you can create a new custom insurance with the fields populated as you desire and then link it to the appropriate providers.

Note: We are working on functionality to allow for bulk updates!

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/12403618-49d5-43ee-99ad-5e99194fe05c' \
  -H 'authorization: Token <your_token>'

❗️

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.


What’s Next