GuidesTry Ribbon!

Edit a Provider's Locations

Suggest Edits

Overview

Description: These endpoints allow you to add or delete locations associated with a provider, as well as append locations with new data, on a provider level.

Endpoints: /v1/custom/providers/{npi}/locations and /v1/custom/providers/{npi}/locations/{uuid}

Status: Live

Methods: PUT

Example use-case: You call a phone number and learn that the phone number is no longer in service. You also confirm from another phone number that the doctor can be reached at that location and now you want to edit the phone numbers for that location to reflect this

Diving In, Using /v1/custom/providers/{NPI}/locations/{UUID}

Altering locations is an interesting use case -- in many ways, it is a merge between being highly flexible like editing "Any Doctor Field" is, but has some constraints the way that specialties and insurances do. Let's get into it!

First off, let us look at a provider to get a sense of what these locations objects look like for a given provider:

{
    "npi": 1003837865,
    "first_name": "Raasheen",
    "last_name": "Thrower",
    "locations": [{
            "uuid": "2ac137de-3dd9-4391-91f0-4409588693b2",
            "name": "Thrower Raasheen MD",
            "address": "333 S State St # 200, Chicago, IL 60604, USA",
            "address_details": {
                "street": "333 S State St # 200",
                "city": "Chicago",
                "state": "IL",
                "zip": "60604"
            },
            "google_maps_link": "https://www.google.com/maps/place/?q=place_id:ChIJSfu72KIsDogR4-ZSzd0VKvY",
            "latitude": 41.8775128,
            "longitude": -87.6271581,
            "phone_numbers": [
                {
                    "phone": "3127479442",
                    "details": "primary"
                }
            ],
            "confidence": 4
        },
  
        ...3 other locations...
    ]
  ...other fields...
}

🚧

Each Location Object has a Set of Immutable Fields

Each location object has a set of immutable fields that cannot be edited, removed, or altered in any way. These immutable fields are uuid, google_maps_link, latitude, and longitude.

For any location object, any field except for the ones above can be added, removed, or altered.

Back to our use case -- we just tried calling the number of the above place that was provided by the API, and it turns out it is no longer in service, and the doctor has a new phone number. To make this change, for this doctor, we submit the following to v1/custom/providers/1003837865/locations/2ac137de-3dd9-4391-91f0-4409588693b2:

{
    "phone_numbers": [
    {
      "phone": "3127479870",
      "details": "primary"
    }
  ]
}

Our PUT request would look as follows:

curl -X PUT \
  'https://api.ribbonhealth.com/v1/custom/providers/1003837865/locations/2ac137de-3dd9-4391-91f0-4409588693b2' \
  -H 'authorization: Bearer <your_token>'
  -F 'body={
    "phone_numbers": [
        {
          "phone": "3127479870",
          "details": "primary"
        }
      ]
    }'

And if we look at this doctor now, we'll see that the change has been reflected instantly!

{
    "npi": 1003837865,
    "first_name": "Raasheen",
    "last_name": "Thrower",
    "locations": [{
            "uuid": "2ac137de-3dd9-4391-91f0-4409588693b2",
            "name": "Thrower Raasheen MD",
            "address": "333 S State St # 200, Chicago, IL 60604, USA",
            "address_details": {
                "street": "333 S State St # 200",
                "city": "Chicago",
                "state": "IL",
                "zip": "60604"
            },
            "google_maps_link": "https://www.google.com/maps/place/?q=place_id:ChIJSfu72KIsDogR4-ZSzd0VKvY",
            "latitude": 41.8775128,
            "longitude": -87.6271581,
            "phone_numbers": [{
                              "phone": "3127479870",
                              "details": "primary"
                            }],
            "confidence": 4
        },  
        ...3 other locations...
    ]
}

🚧

Be careful when setting up an interface to enable editing providers and locations

There is only basic data validation for stock Ribbon Fields if you are on API version [2021-05-13] or later. Previous versions of the API don't have any validation at all.

Please refer to this changelog for more documentation on data type validation for stock Ribbon Fields.

🚧

Be careful of editing a location's address

If you wish you change the 'address' of a location, you would be better suited to create a new location altogether with the desired address and then attach it to the given provider. As mentioned above, the lat/long and link are immutable, therefore if you update a provider location's address from 100 Main Street to 1000 Main Street which is a mile away, the lat/long will not update. Instead, you should create a new location object (docs) at the desired address (e.g. 1000 Main Street) and then attach it to the given provider, shown below.

🚧

Edits at this endpoint are on a Provider <> Location Basis

When you edit a location like this, you are only editing this location on a provider basis. So, if you change phone number data like this for this provider, if another provider is at this location, your changes won't be reflected for that provider at this location (uuid).

For removing fields, it's like it is for doctors, where we make use of the remove_fields field. Let's say you decide our phone numbers and confidence level is not reliable, and you want to remove the fields:

{
    "remove_fields": ["phone_numbers", "confidence"]
}

We submit via the PUT method, as usual:

curl -X PUT \
  'https://api.ribbonhealth.com/v1/custom/providers/1234567890/locations/2ac137de-3dd9-4391-91f0-4409588693b2' \
  -H 'authorization: Bearer <your_token>'
  -F 'body={
    "remove_fields": ["phone_numbers", "confidence"]
}'

And that's it, those fields will be removed!

Diving In, Using /v1/custom/providers/{NPI}/locations

Just like for insurances and specialties, adding or deleting locations from a provider has a similar schema. Let's say, we learn that the doctor above has simply stopped practicing at a location, and therefore we want to remove it from this doctor. Given that the location's UUID is 2ac137de-3dd9-4391-91f0-4409588693b2, we set it up for removal as follows:

{
  "add": [],
  "remove": ["2ac137de-3dd9-4391-91f0-4409588693b2"]
}

curl -X PUT \
  https://api.ribbonhealth.com/v1/custom/providers/1447232251/locations \
  -H 'Authorization: Bearer <your_token>' \
  -d '{
"remove": ["588c06a4-3e26-416b-849b-f20b2104ba0f"]
}'

Submitting the above will go ahead and remove that location UUID, and all of its contents from the doctor!

📘

Provider <> Locations

If you add a new location UUID, as previously stated, the phone numbers and confidence scores won't come when that location is added -- this is because all data beyond the core fields (uuid, name,address,address_details,google_maps_link, latitude, and longitude) need to be specified on a unique doctor basis, for that location.

Like in v1/custom/providers/npi/1234567890/insurances, we can use the override parameter in the JSON schema to list all of the location UUIDs that should override all others for that doctor:

{
  "override": ["dd4ccf99-a5b6-437f-b083-97edaca7a015"]
}

Now you might be wondering -- what if I want to create my own location objects? Have no fear -- see below for information about the endpoint designed just for that!

Updated 26 days ago

What’s Next