Search for Specialties

Overview

Each of Ribbon's Specialties has a unique UUID and set of attributes that correspond to information found in the NUCC taxonomy. You can use the specialty or specialty_ids parameters to search for providers by these specialties in Ribbon's /providers endpoint. There are important differences between the two:

• specialty_ids searches for provider by the exact Ribbon specialty UUID, which corresponds to a distinct specialty in the NUCC Taxonomy).
• specialty searches for providers by specialty groupings. Don't worry, we'll explain more!

Specialty Groupings

Searching for individual specialties can be too granular and lead to low coverage. These granular specialties may not even be needed to navigate patients to the right parameter. We may want to see a cardiologist - it doesn't particularly matter what kind.

Ribbon has created groupings of specialties to allow users to search for these broader specialty categories. For example, the 'Gastroenterology' grouping maps to individual specialties for Gastroenterology, Hepatology, Pediatric Gastroenterology, and a few others. These groupings are exposed through the specialty parameter.

In each API request, you can see a full list of the grouped specialties in the inclusions field of the response.

https://api.ribbonhealth.com/v1/custom/providers?specialty=Gastroenterology

    "inclusions": {
        "specialty_ids": [
            "cf328877-90b9-4b15-9ab4-10f325ffb909",
            "b9dc44e1-6add-41f8-8df4-a8ef9cea706a",
            "28aaf52d-982d-43ed-836f-81223445f545",
            "35658ab3-8ed3-4ad4-939a-c8f05e4fcb80",
            "3ed5ced6-217e-4037-8784-fe5afad0879b"
        ]
    }

Specialty UUIDs

We may actually just want to search by individual specialties using the specialty_ids parameter. Let's search for a specific Gastroenterology UUID in the /specialties reference endpoint. This returns a short list of closely matching specialties, which we can narrow down to the most relevant one for our provider search.

https://api.ribbonhealth.com/v1/custom/specialties?search=Gastroenterology

Search for Providers by Specialty

Let's try searching for gastroenterologists in Denver. As mentioned before, we can use either the specialty parameter:

https://api.ribbonhealth.com/v1/custom/providers?specialty=Gastroenterology&address=Denver

or alternatively, the specialty_ids parameter:

https://api.ribbonhealth.com/v1/custom/providers?specialty_ids=ca571ba5-da97-4c9a-8289-2aaac198d4b2&address=Denver

In the API response, we can see that using the specialty parameter returns a higher count of providers. This is expected - the Ribbon API is matching on the larger set of specialty UUIDs.

📘

Which parameter should I use?

That depends on the level of granularity you're looking for in search requests. Using the specialty parameter can expand coverage, but it will also return a broader range of related specialties than the more specific specialty_ids specialty search.

Primary Care Specialty

Primary care is not a specialty recognized by the National Plan and Provider Enumeration System (NPPES). This makes it challenging to identify providers as PCPs. Ribbon has created a PCP specialty that applies custom logic to determine whether a provider is likely to be a PCP based on available specialty information. However, this specialty (UUID 0c949aa8-6729-41c2-9d3a-5bd4a6966363) isn't directly assigned to any providers and thus cannot be searched using the specialty_ids parameter.

How to search for PCPs

We can surface primary care providers in the API by searching for providers with the specialty parameter ‘Primary Care’. You can combine this specialty parameter with other relevant parameters, (ie address, location_insurance_ids, min_location_confidence, etc.) to further narrow down search results.

https://api.ribbonhealth.com/v1/custom/providers?address=Chicago,IL&distance=5&specialty=Primary

🚧

What if I'm already using specialty_ids?

That's okay! You can split your provider search experience to use the specialties parameter when searching for PCPs and the specialty_ids parameter for other specialty searches.