Create a Custom Filter

Note, this is a premium feature and may not be enabled in your API index. Please reach out to Ribbon Support ([email protected]) for additional information on accessing Custom Filters!

Create the filter

There are 4 fields we need to specify in order to create a new filter:

  • parameter is what will be used when you want to pass your filter through /v1/custom/providers
  • field is the field in the provider object that will be used to filter results
  • value_type is either "string", "float", "integer", "boolean", or "list". This tells us what kind of value the field is.
  • filter_type is one of either "less_than", "greater_than", "equals", "equals_any", or "contains"

To create a filter for providers who have a patient satisfaction rating of greater than 5.0, we would specify the following request body:

{
  "filter_type": "greater_than",
  "value_type": "float",
  "parameter": "patient_rating",
  "field": "ratings_avg"
}

We can then make a POST request to Ribbon's API to actually create the filter!

curl -X POST \
  https://api.ribbonhealth.com/v1/custom/providers/filters \
  -H 'Authorization: Bearer <Your Token>' \
  -d '{
  "filter_type": "greater_than",
  "value_type": "float",
  "parameter": "patient_rating",
  "field": "ratings_avg"
}'

While the filter gets added to your database, please wait at least 2 minutes before continuing and testing further. We can now get a look at all of the filters we've created with the following GET request:

https://api.ribbonhealth.com/v1/custom/providers/filters

Apply the filter

Now, if we only want to show providers in our search that have a patient satisfaction rating above 5, we can do so by searching the /providers endpoint with the following GET request. Let's also try specifying the fields parameter to simplify the search result for visibility purposes!

https://api.ribbonhealth.com/v1/custom/providers?patient_rating=7&fields=ratings_avg

In the API Response, we can see a list of provider NPIs and corresponding patient rating scores, which are all above 7.0!