Edit a Provider's Insurances
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)
Updated over 2 years ago
To learn how to look up and create your own insurance plan objects: