Add or Edit Provider Fields

Overview

Description: This endpoint allows you to edit all other fields that do not fall under specialties, locations, and insurances. This includes adding new fields!

Endpoints: /v1/custom/providers/{npi}

Status: Live

Methods: PUT

Example use-case: You want to add a new field to doctors to display quality metrics that Ribbon does not yet expose, such as C-Section rates.

Diving In

Adding Fields to a Provider:
For this use-case, we'll use an example. Let's say we want to add a unique quality metric that pertains to a certain group of providers. In this case, C-Section rates for OBGYNs.

For this illustrative example, the metric is a float between 0 and 100. The way we would add this to any doctor, so long as we have their NPI, is shown below.

The JSON document we would use to add this new data field to a doctor is as such:

JSON

{
  "npi": 1659515591,
  "c_section_rate": 8.3
}

We submit this JSON document through the /v1/custom/providers/npi endpoint, as a PUT request:

cURL

curl -X PUT \
  'https://api.ribbonhealth.com/v1/custom/providers/1659515591' \
  -H 'authorization: Bearer <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "npi": 1659515591,
  "c_section_rate": 8.3
}'

If this is successful, we'll get the following JSON in a 200 response:

JSON

{
  "data": {
    "npi": 1659515591,
    "c_section_rate": 8.3
  }
}

Everything looks good -- let's see what happens when we call this doctor at /v1/custom/providers/1659515591 to see if this really worked!

JSON

{
  "first_name": "Amy",
  "middle_name": "Lauren",
  "last_name": "Turitz",
  "npi": "1659515591",
  "c_section_rate": 8.3,
  "age": 36,
  "gender": "f",
  "ratings_count": 5,
  "ratings_avg": 8,
...other fields...
}

Why, by the Beard of Zeus, it worked! We can see that this doctor now has the field c_section_rate with a value of 8.3.

Updating Fields of a Provider:
Now, what if we get new data, and want to update this field? And not only do we want to update this field, but we want to add the number of data points associated with this doctor that led to our calculation of their C-section rate.

We submit the following JSON:

JSON

{
  "npi": 1659515591,
  "c_section_rate": 7.8,
  "c_section_sample_size": 435
}

And we'll see that when we look at this doctor, we see that we've not only added a new field, but c_section_rate and c_section_sample_size will be updated:

JSON

{
  "first_name": "Amy",
  "middle_name": "Lauren",
  "last_name": "Turitz",
  "npi": "1659515591",
  "c_section_rate": 7.8,
  "c_section_sample_size": 435,
  "age": 36,
  "gender": "f",
  "ratings_count": 5,
  "ratings_avg": 8,
...other fields...
}

🚧

New feature in API Version [2021-05-13]

We have released a new feature that introduces data type validation to stock Ribbon Fields in API Version [2021-05-13].

For more information, please refer to this changelog.

📘

Update custom fields as well as stock Ribbon fields

Note that you are able to update custom fields that you have added to a provider (i.e. C-Section rate) as well as stock Ribbon fields (i.e. age).

Updating specialties, insurances, and locations follows a different process that we will cover in later sections.

Deleting Fields of a Provider:
In order to delete fields of a provider, we have a specified JSON schema to do so. The reason we do not use the DELETE method here is that method is used for deleting the entire doctor object. Instead, we still use the PUT method.

The format of the JSON Schema is as follows:

JSON

{
  "npi": 1659515591,
  "remove_fields": ["c_section_sample_size", "c_section_rate"]
}

We submit this as a PUT request, and the doctor will be updated! We can see this doctor no longer has either field:

JSON

{
  "first_name": "Amy",
  "middle_name": "Lauren",
  "last_name": "Turitz",
  "npi": "1659515591",
  "age": 36,
  "gender": "f",
  "ratings_count": 5,
  "ratings_avg": 8,
...other fields...
}

Use Case	Requirements
Submitting or updating any new field for a doctor	- Valid JSON - None of the fields are remove_fields, locations, insurances, or specialties
Removing doctor fields	- Valid JSON - The only field beyond npi is remove_fields