GuidesTry Ribbon!

Create New Provider Search Filters

Suggest Edits

Overview

Description: The listings and search endpoint allows you to quickly pull providers based on important search criteria.

Endpoint: /v1/custom/providers/filters

Status: Live

Methods: GET, POST

Description: This endpoint allows you to create new filters to be used when searching for providers in the /v1/custom/providers endpoint. You can create filters for both Ribbon's existing data fields as well as any custom data fields you create.

Example Use Case:
Let's say you add a new field to a bunch of providers that match your use case, for instance c_section_rate. You could make this field searchable so that your search through v1/custom/providers when you pass through a certain parameter that specifies a maximum threshold.

Diving In

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", or "contains"

To create a filter for doctors who have a C-section rate less than a certain threshold, we have:

{
  "filter_type": "less_than",
  "value_type": "float",
  "parameter": "max_c_section_rate",
  "field": "c_section_rate"
}

So, before we go through the process of creating this filter, let's break this down. What does this mean?

If we want to only show doctors in our search that have a c_section_rate below 15.5, we would be able to do so by searching v1/custom/providers?max_c_section_rate=15.5. Awesome!

Let's create this filter:

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

Awesome. 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 of all of the filters we've created at doing a GET request at v1/custom/providers/filters:

{
  "data": [{
    "uuid": "9da04268-65e4-4422-a095-98208695b8b9",
    "filter_type": "less_than",
    "value_type": "float",
    "parameter": "max_c_section_rate",
    "field": "c_section_rate"
  }]
}

Let's say we updated just one provider object with a field named c_section_rate set to 8.3, like we did in the example under "Edit any Doctor Field". Then, if we do a GET call to v1/custom/providers?max_c_section_rate=2 we get no results:

{
  "parameters": {
    "page": 1,
    "page_size": 25,
    "sort_by": "distance",
    "distance": 1,
    "geo": {
      "latitude": 40.7351327,
      "longitude": -73.9903544
    },
    "address": "33 Irving Pl, New York, NY 10003, USA"
  },
  "data": []
}

Since all doctors do not have this field, and the one doctor we did update was set to 8.3, it's not surprising we got no results! So lets move up our call up to 10: v1/custom/providers?max_c_section_rate=10. Now, when we do a GET, we actually get the one doctor we updated!

{
  "parameters": {
    "page": 1,
    "page_size": 25,
    "sort_by": "distance",
    "distance": 1,
    "geo": {
      "latitude": 40.7351327,
      "longitude": -73.9903544
    },
    "address": "33 Irving Pl, New York, NY 10003, USA"
  },
  "data": [
    {
      "first_name": "Amy",
      "middle_name": "Lauren",
      "last_name": "Turitz",
      "c_section_rate": 8.3,
      "age": 36,
      "gender": "f",
      "ratings_count": 5,
      "ratings_avg": 8,
      "degrees": [...],
      "specialties": [...],
            "languages": ["english"],
      "educations": [...],
            "insurances": [...],
      "provider_types": ["Doctor"],
      "locations": [...],
      "online_profiles": [...],
      "npi": 1659515591
    }
  ]
}

There is a lot that can be done here. Our mission to allow you to manipulate your provider search as easily as possible!

Nested Querying

You might be wondering -- can I create filters that navigate multiple levels of a doctor's JSON Schema? The answer is yes!

📘

Get creative with nested querying!

You can add filters that are nested; that is you can go down multiple "levels" in the JSON schema

Let's say that we wanted to do a listing/searching that does not come out of the box with the Ribbon API, that is, list doctors that went to a certain medical school, such as Weill Cornell Medical College. We can see that the structure of the JSON Schema to get to the UUID is educations > education > uuid:

{
            "first_name": "John",
            "middle_name": "F",
            "last_name": "Romano",
            "degrees": [...],
            "specialties": [...],
            "languages": [...],
            "educations": [
               {
                    "education": {
                        "name": "Weill Cornell Medical College",
                        "uuid": "3d66a876-920b-45cf-8f6c-788ceb74235c"
                    },
                    "type": null,
                    "year": 1973
                }
            ],
  }

Therefore, if we want to create a filter that receives an education UUID, we can create the filter and perform a nested query search by structuring the field as educations.education.uuid, like so:

curl -X POST \
  https://api.ribbonhealth.com/v1/custom/doctors/filters \
  -H 'Authorization: Bearer <Your Token>' \
  -d '{
  "filter_type": "equals",
  "value_type": "string",
  "parameter": "education_id",
  "field": "educations.education.uuid"
}'

📘

When you create a new filter, you can set the name for your new search parameter

In the example above, "parameter": "education_id", we are designating our new filter to be called using the parameter value "education_id". Conducting a search with this parameter is shown below.

Now that we've created the above filter, we can now list all doctors who went to Harvard Medical School by using the UUID 3d66a876-920b-45cf-8f6c-788ceb74235c:

curl -X GET \
  'https://api.ribbonhealth.com/v1/custom/doctors?education_id=3d66a876-920b-45cf-8f6c-788ceb74235c' \
  -H 'Authorization: Bearer <Your Token>' \
  -H 'Content-Type: application/json'

Updated 26 days ago