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.

HTTP

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

JSON

    "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.

HTTP

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:

HTTP

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

or alternatively, the specialty_ids parameter:

HTTP

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.

Inclusion/Exclusion Logic

As mentioned above, Ribbon has created custom logic to identify a provider as a PCP based on their assigned specialties in NPPES. If a provider is associated with 1 or more specialties on the inclusion list below, without any specialties not on the list, they would be considered eligible to be a PCP. For instance:

• Internal Medicine & Internal Medicine Critical Care Medicine = Not PCP
• Family Medicine = PCP
• Family Medicine & Adult Medicine = PCP

Inclusion List:

• Internal Medicine, 475b20fc-c188-4ca1-8e3a-b0614b8f8ce2
• Internal Medicine - Geriatric Medicine, 70da755b-f382-4957-a0d0-cb41b2d45d70
• Internal Medicine - Adolescent Medicine, 31ff2eb3-559e-4b32-88e3-19654457633e
• Family Medicine, 18d8ad26-7e5f-44ac-9afa-966efb375344
• Family Medicine - Geriatric Medicine, 058148f1-3a99-4bbe-9722-6c2a54ddb860
• Family Medicine - Adult Medicine, ec41ff31-571d-422e-a8b5-806bed6a6c04
• Family Medicine - Adolescent Medicine, a1539b13-b557-437b-aae4-9ff241171020
• Pediatrics, d6f8893a-9637-4565-8202-1173e02c0979
• Pediatrics - Adolescent Medicine, 210f358e-d037-49aa-9891-f1f655fc64ec
• General Practice, e5047409-3007-4a04-aff9-07604bd10287
• Nurse Practitioner - Primary Care, 5d8058f9-b2c7-4556-8870-22d47b2ec03c
• Nurse Practitioner - Gerontology, 74a88d8d-6dcc-45d2-ac9c-5bbff6a2fc6b
• Nurse Practitioner - Family, 066e8fe9-45e1-486c-b80f-7b93708bb329
• Nurse Practitioner - Women's Health, c350d7ac-f912-4909-8a3d-7aebd46c5c70
• Nurse Practitioner - Pediatric, bf8fb610-7aa8-4ced-b9e1-98d1ec13c2e2
• Primary Care Provider, 0c949aa8-6729-41c2-9d3a-5bd4a6966363

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.

HTTP

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.