GuidesTry Ribbon!

Specialties Endpoint

Suggest Edits

Overview

Description: This endpoint allows you to search through provider specialties that exist within the Ribbon API.

If you are leveraging a Custom Provider Index, then you can also use this endpoint to create and edit your own specialties.

Endpoints:
Standard Index: /v1/specialties/ and /v1/specialties/{UUID}
Custom Index: /v1/custom/specialties/ and /v1/custom/specialties/{UUID}

Status: Live

Methods:
Standard Index: GET
Custom Index: GET, PUT, POST, DELETE

Example use-case:
You want your users to be able to select from a drop down list of available provider specialties (i.e. Cardiology), which you power through GET requests to this endpoint.

Diving In - Searching & Viewing Specialties

To search across the specialties endpoint, you can use GET requests.

Add the "search" parameter to get a paginated list of all available specialties. This parameter will run a 'fuzzy' search against key fields within each specialties object to return the most relevant options.

For example, if you are looking for gastroenterologists, you could conduct a call as follows:

curl -X GET \
  'https://api.ribbonhealth.com/v1/custom/specialties?search=Gastroenterology' \
  -H 'authorization: Bearer <your_token>'

We'll see our response:

{
    "count": 3,
    "next": null,
    "previous": null,
    "results": [
        {
            "uuid": "ca571ba5-da97-4c9a-8289-2aaac198d4b2",
            "taxonomy_code": "207RG0100X",
            "provider_name": "Gastroenterologist",
            "colloquial": "Stomach Doctor",
            "board_specialty": "Internal Medicine",
            "board_sub_specialty": "Gastroenterology",
            "non_md_specialty": null,
            "non_md_sub_specialty": null,
            "taxonomy_1": "Allopathic & Osteopathic Physicians",
            "taxonomy_2": "Internal Medicine",
            "taxonomy_3": "Gastroenterology",
            "display": "Gastroenterology",
            "provider_type": "Doctor"
        },
        {
            "uuid": "f97d7692-d8dd-448e-ab9a-21ea70289621",
            "taxonomy_code": "2080P0206X",
            "provider_name": "Pediatric Gastroenterologist",
            "colloquial": "Children & Adolescent Stomach Doctor",
            "board_specialty": "Pediatrics",
            "board_sub_specialty": "Pediatric Gastroenterology",
            "non_md_specialty": null,
            "non_md_sub_specialty": null,
            "taxonomy_1": "Allopathic & Osteopathic Physicians",
            "taxonomy_2": "Pediatrics",
            "taxonomy_3": "Pediatric Gastroenterology",
            "display": "Pediatrics - Gastroenterology",
            "provider_type": "Doctor"
        },
                ... 1 more specialty ...
    ]
}

👍

'Fuzzy' Search Using the Specialties Endpoint

The specialties endpoint's "search" parameter allows for fuzzy searching as well!

For example, any of the following calls would return the same list of Gastroenterology related specialties as you see above:
https://api.ribbonhealth.com/v1/custom/specialties?search=Gastroenterology
https://api.ribbonhealth.com/v1/custom/specialties?search=Gastroenterologist
https://api.ribbonhealth.com/v1/custom/specialties?search=Stomach Doc
https://api.ribbonhealth.com/v1/custom/specialties?search=Gastro
https://api.ribbonhealth.com/v1/custom/specialties?search=Gastroo

In addition to using the "search" parameter, you can add the "provider_type" parameter (as seen at the /provider/ endpoint) to further filter results.

For example, when you search for "Gastroenterology" you will receive 3 results. Two of these results are for specialties for Doctors, while the third is a specialty for Nurses.

If you set provider_type=Doctor, however, you can limit the result to only specialties with the inputted provider type.

Diving In - Creating New Specialties

Now, let's say that we want to deviate from the ~700 CMS standardized specialties we offer.

For instance, let's say that between an Internal Medicine Doctor, Family Medicine and General Practitioner, you want to create an overarching category called Primary Care Physician. We could simply make a POST request to this endpoint, like so:

curl -X POST \
  'https://api.ribbonhealth.com/v1/custom/specialties' \
  -H 'Authorization: Bearer <your_token>' \
  -d '{
    "display": "Primary Care Physician (PCP)",
    "provider_type": "Doctor",
    "taxonomy_code": "",
    "board_specialty": "",
    "board_sub_specialty": "",
    "non_md_specialty": "",
    "non_md_sub_specialty": "",
    "provider_name": "",
    "colloquial": ""
}'

Assuming we did not pass any incorrect fields, we'll get back a valid response:

{
    "data": {
        "uuid": "813c684e-bcb1-4a51-98a2-dc2f8a64871b",
        "taxonomy_code": null,
        "board_specialty": null,
        "board_sub_specialty": null,
        "non_md_specialty": null,
        "non_md_sub_specialty": null,
        "provider_name": null,
        "colloquial": null,
        "display": "Primary Care Physician (PCP)",
        "taxonomy_1": null,
        "taxonomy_2": null,
        "taxonomy_3": null,
        "provider_type": "Doctor"
    }
}

We can now add this specialty to any doctor via the v1/custom/providers/{NPI}/specialties endpoint!

If we didn't do this correctly and now want to edit or delete this custom specialty, we can use the next endpoint, which is a subset of this one!

Diving In - Editing & Deleting Specialties

We can edit a new, custom specialty with a PUT request at /v1/custom/specialties/{UUID}:

curl -X PUT \
  https://api.ribbonhealth.com/v1/custom/specialties/813c684e-bcb1-4a51-98a2-dc2f8a64871b \
  -H 'Authorization: Bearer <your token>' \
  -d '{
    "taxonomy_code": "",
    "board_specialty": "",
    "board_sub_specialty": "",
    "non_md_specialty": "",
    "non_md_sub_specialty": "",
    "provider_name": "",
    "colloquial": "PCP",
    "display": "Primary Care Physician",
    "provider_type": "Doctor"
}'

Upon success, this will update the record!

🚧

POST and PUT requests for specialty creation and editing require all of the above fields to be present, i.e.:
"display", "taxonomy_code", "provider_type", "board_specialty", "board_sub_specialty", "non_md_specialty", "non_md_sub_specialty", "provider_name", "colloquial"

Now, perhaps we REALLY screwed up and want to delete a custom specialty all together? We can merely submit a DELETE request to the v1/custom/specialties/{UUID} endpoint, like so:

curl -X DELETE \
  https://api.ribbonhealth.com/v1/custom/specialties/813c684e-bcb1-4a51-98a2-dc2f8a64871b \
  -H 'Authorization: Bearer <your token>'

🚧

You can only edit and delete custom specialties

You cannot edit or delete the specialties that Ribbon provides (although you can remove specialties from a provider record). If you want to 'edit' a specialty, you can create a new custom specialty with the fields populated as you desire and then link it to the appropriate providers.

Note: We are working on functionality to allow for bulk updates!

❗️

Be careful when deleting a custom specialty!

Once you delete it, you cannot get it back, and all the doctors that you added it to will no longer have it!

Updated 26 days ago