GuidesTry Ribbon!

Exclude Providers from Search

Suggest Edits

Overview

Description: Any filter parameter, including ones created by the user, can be transformed into an exclusion filter by simply prepending the parameter with _excl_

Endpoint: /v1/custom/providers

Status: Live

Methods: GET

Example use-case: You want to find OBGYNs in an area that takes a certain insurance, but want to exclude doctors that work at a certain medical facility known to be expensive and also exclude "Gynaecologist" and "Oncology OBGYN" specialists, due to wanting to list more generalist practitioners.

Diving In

Let's do a regular search for just OBGYNs (specialty UUID 9c470211-e3ea-4963-9568-8d8e9b8f5c44) within 5 miles:

curl -X GET \
  'https://api.ribbonhealth.com/v1/custom/providers?specialty_ids=9c470211-e3ea-4963-9568-8d8e9b8f5c44&distance=5' \
  -H 'Authorization: Bearer <Your Token>' \

Lovely! We can see that we get 1489 results for this search in the NYC area:

{
    "parameters": {
        "total_count": 1489,
        "page": 1,
        "page_size": 25,
        "sort_by": "distance",
        "distance": 5,
        "geo": {
            "latitude": 40.7351327,
            "longitude": -73.9903544
        },
        "address": "33 Irving Pl, New York, NY 10003, USA",
        "specialty_ids": [
            "9c470211-e3ea-4963-9568-8d8e9b8f5c44"
        ]
   },
    "data": [...]
}

So let's see what happens when we add the following exclusions:

In order to exclude Gynaecologists (d8f7fff0-9c5b-42e2-b011-376315d4be3d) and Gynecologic Oncologists (3df73eed-c956-409e-9d79-5df2208abff7), we add: _excl_specialty_ids=d8f7fff0-9c5b-42e2-b011-376315d4be3d,3df73eed-c956-409e-9d79-5df2208abff7

📘

A B C, easy as 1 2 3! (Except easy as _excl_)

You can add excl to any filter parameter to turn that filter into an exclusion!

Our search will look like:

curl -X GET \
  'https://api.ribbonhealth.com/v1/custom/providers?specialty_ids=9c470211-e3ea-4963-9568-8d8e9b8f5c44&_excl_specialty_ids=d8f7fff0-9c5b-42e2-b011-376315d4be3d,3df73eed-c956-409e-9d79-5df2208abff7' \
  -H 'Authorization: Bearer <Your Token>' \

This yields us a total of 1250, which removed ~200 providers from that search, to ensure our results include generalist OBYGNs:

{
    "parameters": {
        "total_count": 1250,
        "page": 1,
        "page_size": 25,
        "sort_by": "distance",
        "distance": 5,
        "geo": {
            "latitude": 40.7351327,
            "longitude": -73.9903544
        },
        "address": "33 Irving Pl, New York, NY 10003, USA",
        "exclusions": {
            "specialty_ids": [
                "d8f7fff0-9c5b-42e2-b011-376315d4be3d",
                "3df73eed-c956-409e-9d79-5df2208abff7"
            ]
        },
        "specialty_ids": [
            "9c470211-e3ea-4963-9568-8d8e9b8f5c44"
        ]
    },
    "data": [...]
}

Finally, we can add the constraint of excluding a location's UUID that is known to be expensive (_excl_location_ids=b8749493-c72e-4bfc-921d-20772232cba5), and also limiting to providers who accept BCBS Blue Card (insurance_ids=e527f6e3-fe42-4932-bf34-d81f1c1fd652):

curl -X GET \
  'https://api.ribbonhealth.com/v1/custom/providers?specialty_ids=9c470211-e3ea-4963-9568-8d8e9b8f5c44&_excl_specialty_ids=d8f7fff0-9c5b-42e2-b011-376315d4be3d,3df73eed-c956-409e-9d79-5df2208abff7&_excl_location_ids=b8749493-c72e-4bfc-921d-20772232cba5&insurance_ids=e527f6e3-fe42-4932-bf34-d81f1c1fd652&distance=5' \
  -H 'Authorization: Bearer <Your Token>' \

{
    "parameters": {
        "total_count": 705,
        "page": 1,
        "page_size": 25,
        "sort_by": "distance",
        "distance": 5,
        "geo": {
            "latitude": 40.7351327,
            "longitude": -73.9903544
        },
        "address": "33 Irving Pl, New York, NY 10003, USA",
        "exclusions": {
            "specialty_ids": [
                "d8f7fff0-9c5b-42e2-b011-376315d4be3d",
                "3df73eed-c956-409e-9d79-5df2208abff7"
            ],
            "location_ids": [
                "b8749493-c72e-4bfc-921d-20772232cba5"
            ]
        },
        "specialty_ids": [
            "9c470211-e3ea-4963-9568-8d8e9b8f5c44"
        ],
        "insurance_ids": [
            "e527f6e3-fe42-4932-bf34-d81f1c1fd652"
        ]
    },
    "data": [...]
}

This reduced our initial general search of 1489 providers into a focused one of 705. Adding thoughtful exclusions can help ensure high-quality search experiences for the user!

Updated 26 days ago