Edit a Location's Insurances
Overview
Description: This endpoint allows you to add or delete insurances from a location in a standardized way, using our standard insurance UUID
Endpoint: /v1/custom/locations/{uuid}/insurances
Status: Live
Methods: PUT
Example use-case: You learn that a location accepts an insurance that isn't listed. You can go ahead and add that insurance, or delete one that they no longer accept.
Diving In
You'll notice when hitting our v1/custom/locations
endpoint that for every insurance a location 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
.
{
"uuid": "3814bx4d-281f-47c2-a3ff-0e5834e41721",
"name": "HourClinic",
"address": "188 Grand St, New York, NY 10013, US",
"address_details": {
"street": "188 Grand St",
"address_line_1": "188 Grand St",
"address_line_2": null,
"city": "New York",
"state": "NY",
"zip": "10013"
},
"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 location 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
(see documentation on this here) 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/locations/3814bx4d-281f-47c2-a3ff-0e5834e41721/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 location again, we'll see that they have been updated:
"uuid": "3814bx4d-281f-47c2-a3ff-0e5834e41721",
"name": "HourClinic",
"address": "188 Grand St, New York, NY 10013, US",
"address_details": {
"street": "188 Grand St",
"address_line_1": "188 Grand St",
"address_line_2": null,
"city": "New York",
"state": "NY",
"zip": "10013"
},
"latitude": 40.719511,
"longitude": -73.9970748,
"google_maps_link": "https://www.google.com/maps/@40.719511,-73.9970748?q=188%20Grand%20St%2C%20New%20York%2C%20NY%2010013%2C%20US",
"location_types": [
"Retail Clinic"
],
"phone_numbers": [
{
"phone": "6463456789"
}
],
"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 location 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/locations/{uuid}/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:
"uuid": "3814bx4d-281f-47c2-a3ff-0e5834e41721",
"name": "HourClinic",
"address": "188 Grand St, New York, NY 10013, US",
"address_details": {
"street": "188 Grand St",
"address_line_1": "188 Grand St",
"address_line_2": null,
"city": "New York",
"state": "NY",
"zip": "10013"
},
"latitude": 40.719511,
"longitude": -73.9970748,
"google_maps_link": "https://www.google.com/maps/@40.719511,-73.9970748?q=188%20Grand%20St%2C%20New%20York%2C%20NY%2010013%2C%20US",
"location_types": [
"Retail Clinic"
],
"phone_numbers": [
{
"phone": "6463456789"
}
],
"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 you're looking for in the custom/insurances
endpoint? We give you the ability to create your own insurance object! (See below)
Updated almost 2 years ago