Overview

Description: This endpoint allows you to add or delete insurances from a provider in a standardized way, using our standard insurance UUID

Endpoint: /v1/custom/providers/{npi}/insurances

Status: Live

Methods: PUT

Example use-case: You learn that a doctor no longer accepts a certain insurance that Ribbon claims they accept. You can go ahead and delete that insurance, or add new ones that they do accept.

Diving In

You'll notice when hitting our v1/custom/providers endpoint that for every insurance a doctor has, we have a standard format, and each insurance has a uuid. Below, we can see two insurance plans for the given doctor:Cigna - HMO, and Humana - HMO.

{
  "first_name": "Jane",
  "last_name": "Doe",
  "npi": "12345890",
  "insurances": [{
                "uuid": "5c1b23af-e735-408d-94c3-c0146b19b180",
                "carrier_association": "Cigna",
                "carrier_brand": "Cigna",
                "carrier_name": "Cigna",
                "plan_name": "HMO",
                "display_name": "Cigna - HMO"
            },
            {
                "uuid": "4c5e24a2-3b8a-40f7-a1aa-275e12136aa7",
                "carrier_association": "Humana",
                "carrier_brand": "Humana",
                "carrier_name": "Humana",
                "plan_name": "HMO",
                "display_name": "Humana - HMO"
            },
                 ...more insurances...
  ],
...other fields...
}

If we learn that this doctor no longer accepts Cigna - HMO, and instead now only accepts Cigna - PPO, we can make that change. To do so, we'll need the respective UUIDs of both in order to delete and add them. Use a GET /v1/custom/insurances request to see all insurance plans and make sure you have the right UUID.

We can see from that endpoint that Cigna - PPO's UUID is de8b20b6-a2e3-460a-9018-9d89c009cef8, the plan we'll add. 5c1b23af-e735-408d-94c3-c0146b19b180 is the plan we'll remove.

The schema structure through this endpoint is as follows:

{
  "add": ["de8b20b6-a2e3-460a-9018-9d89c009cef8"],
  "remove": ["5c1b23af-e735-408d-94c3-c0146b19b180"]
}

We submit this request as follows:

curl -X PUT \
  'https://api.ribbonhealth.com/v1/custom/providers/1234567890/insurances' \
  -H 'authorization: Token <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "add": ["de8b20b6-a2e3-460a-9018-9d89c009cef8"],
  "remove": ["5c1b23af-e735-408d-94c3-c0146b19b180"]
}'

Pending that those are all valid insurance UUID's, we'll get back a successful response!

If we look at the doctor again, we'll see that they have been updated:

{
  "first_name": "Jane",
  "last_name": "Doe",
  "npi": "12345890",
  "insurances": [{
                "uuid": "de8b20b6-a2e3-460a-9018-9d89c009cef8",
                "carrier_association": "Cigna",
                "carrier_brand": "Cigna",
                "carrier_name": "Cigna",
                "plan_name": "PPO",
                "display_name": "Cigna  - PPO"
            },
            {
                "uuid": "4c5e24a2-3b8a-40f7-a1aa-275e12136aa7",
                "carrier_association": "Humana",
                "carrier_brand": "Humana",
                "carrier_name": "Humana",
                "plan_name": "HMO",
                "display_name": "Humana - HMO"
            },
                 ...more insurances...
  ],
...other fields...
}

Now, what if rather than just deleting or adding insurances, you want to do a complete override? For example, if you learn that a doctor just accepts just Medicare and want to delete all the other insurances

You could make a call to get a full list of insurances and delete all of them at once while adding Medicare. Or, you could just use the override field, and submit a schema as follows to the /v1/custom/doctors/npi/insurances endpoint:

{
  "override": ["88afd94e-e6c8-4229-9b4c-7d8c3ee293f6"]
}

This will completely override all other insurances, and replace it with the UUIDs listed. Now, we see:

{
  "first_name": "Jane",
  "last_name": "Doe",
  "npi": "12345890",
  "insurances": [{
                "uuid": "88afd94e-e6c8-4229-9b4c-7d8c3ee293f6",
                "carrier_association": "Medicare",
                "carrier_brand": "Medicare",
                "carrier_name": "Medicare",
                "plan_name": "Medicare",
                "display_name": "Medicare - Medicare"
            }],
...other fields...
}

That's all there is to it -- easy peasy, lemon squeezy!

But wait -- what if we do not have the insurance your looking for in the custom/insurances endpoint? We give you the ability to create your own insurance object! (See below)