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)