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}/locations/{uuid}/insurances

Status: Live

Methods: PUT

Example use-case: You learn that a doctor no longer accepts a certain insurance at a specific location 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: Aetna Premier Plan and Aetna Choice Plan.

{
  "first_name": "Jane",
  "last_name": "Doe",
  "npi": "12345890",
  "insurances": [{...insurance list rolled up to Provider level...},],
  "locations": [
        {
            "bio": "",
            "name": "Jane Doe Office",
            "uuid": "34ecc98a-e49e-49e3-84f9-b0ab2ff00495",
            "awards": [],
            "address": "600 Mamaroneck Ave FL 2, Harrison, NY 10528, US",
            "latitude": 40.9811096,
            "confirmed": false,
            "image_url": null,
            "longitude": -73.7430954,
            "conditions": [],
            "confidence": 4,
            "insurances": [
                {
                    "uuid": "000914b4-d165-4343-bd17-0054505faaa5",
                    "carrier_association": "Aetna",
                    "carrier_brand": "Aetna",
                    "carrier_name": "Aetna",
                    "state": null,
                    "plan_name": "Premier Plan",
                    "plan_type": "PPO",
                    "metal_level": null,
                    "display_name": "Aetna - Premier Plan - PPO",
                    "network": null,
                    "category": "Medicare Advantage",
                    "codes": [
                        "H5521-121"
                    ],
                    "confidence": 4
                },
                {
                    "uuid": "0028c078-12b0-46c0-baa8-5a1e9efb2f85",
                    "carrier_association": "Aetna",
                    "carrier_brand": "Aetna",
                    "carrier_name": "Aetna",
                    "state": null,
                    "plan_name": "Choice Plan",
                    "plan_type": "PPO",
                    "metal_level": null,
                    "display_name": "Aetna - Choice Plan - PPO",
                    "network": null,
                    "category": "Medicare Advantage",
                    "codes": [
                        "H9431-001"
                    ],
                    "confidence": 4
                 },
            ...other locations...
            ],
...other fields...
}

Note that although a provider's insurances will be returned in a rolled up list at the Provider level, they actually live at the Provider.locations level. As a result, when editing insurances, we should always do it at the provider.locations level seen above.

If we learn that this doctor no longer accepts Aetna Premier Plan at this office, and now accepts the Aetna Elite Plan, we can make that change. To do so, we'll need the respective UUIDs in order to delete/add these plans. Use a GET /v1/custom/insurances request to see all insurance plans and make sure you have the right UUIDs.

We can see from that endpoint that Aetna Premier Plan's UUID is 000914b4-d165-4343-bd17-0054505faaa5 (the plan we'll remove), and Aetna Elite Plan's UUID is 003aa14f-31ed-4c20-8888-07055d69afb6(the plan we'll add).

The schema structure through this endpoint is as follows:

{
  "add": ["003aa14f-31ed-4c20-8888-07055d69afb6"],
  "remove": ["000914b4-d165-4343-bd17-0054505faaa5"]
}

We submit this request as follows:

curl -X PUT \
  'https://api.ribbonhealth.com/v1/custom/providers/1234567890/locations/34ecc98a-e49e-49e3-84f9-b0ab2ff00495/insurances' \
  -H 'authorization: Bearer <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "add": ["003aa14f-31ed-4c20-8888-07055d69afb6"],
  "remove": ["000914b4-d165-4343-bd17-0054505faaa5"]
}'

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": [{...insurance list rolled up to Provider level...},],
  "locations": [
        {
            "bio": "",
            "name": "Jane Doe Office",
            "uuid": "34ecc98a-e49e-49e3-84f9-b0ab2ff00495",
            "awards": [],
            "address": "600 Mamaroneck Ave FL 2, Harrison, NY 10528, US",
            "latitude": 40.9811096,
            "confirmed": false,
            "image_url": null,
            "longitude": -73.7430954,
            "conditions": [],
            "confidence": 4,
            "insurances": [
                {
                    "uuid": "0028c078-12b0-46c0-baa8-5a1e9efb2f85",
                    "carrier_association": "Aetna",
                    "carrier_brand": "Aetna",
                    "carrier_name": "Aetna",
                    "state": null,
                    "plan_name": "Choice Plan",
                    "plan_type": "PPO",
                    "metal_level": null,
                    "display_name": "Aetna - Choice Plan - PPO",
                    "network": null,
                    "category": "Medicare Advantage",
                    "codes": [
                        "H9431-001"
                    ],
                    "confidence": 4
                },
                {
                      "uuid": "003aa14f-31ed-4c20-8888-07055d69afb6",
                      "carrier_association": "Aetna",
                      "carrier_brand": "Aetna",
                      "carrier_name": "Aetna",
                      "state": null,
                      "plan_name": "Elite Plan",
                      "plan_type": "HMO",
                      "metal_level": null,
                      "display_name": "Aetna - Elite Plan - HMO",
                      "network": null,
                      "category": "Medicare Advantage",
                      "codes": [
                          "H5793-010"
                      ],
                      "confidence": 4
                  },
            ...other locations...
            ],
...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/locations/insurances endpoint:

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

We submit this request as follows:

curl -X PUT \
  'https://api.ribbonhealth.com/v1/custom/providers/1234567890/locations/34ecc98a-e49e-49e3-84f9-b0ab2ff00495/insurances' \
  -H 'authorization: Bearer <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "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": [{...insurance list rolled up to Provider level...},],
  "locations": [
        {
            "bio": "",
            "name": "Jane Doe Office",
            "uuid": "34ecc98a-e49e-49e3-84f9-b0ab2ff00495",
            "awards": [],
            "address": "600 Mamaroneck Ave FL 2, Harrison, NY 10528, US",
            "latitude": 40.9811096,
            "confirmed": false,
            "image_url": null,
            "longitude": -73.7430954,
            "conditions": [],
            "confidence": 4,
            "insurances": [
                {
                   "uuid": "88afd94e-e6c8-4229-9b4c-7d8c3ee293f6",
                    "carrier_association": "Medicare",
                    "carrier_brand": "Medicare",
                    "carrier_name": "Medicare",
                    "plan_name": "Medicare",
                    "state": null,
                    "plan_name": "Medicare",
                    "metal_level": null,
                    "display_name": "Medicare - Medicare",
                    "network": null,
                    "category": "Medicare",
                    "codes": ["H9047-805"],
                    "confidence": 4
                },
            ...other locations...
            ],
...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)