List and Create Provider Specialties

Overview

Description: This endpoint allows you to see all specialties, including the ones you have created, as well as create new specialties.

Endpoints: /v1/custom/specialties and /v1/custom/specialties/{UUID}

Status: Live

Methods: GET,POST, DELETE

Example use-case: You want to add a specialty to a provider, but it does not yet exist -- so you create a new specialty through the POST method.

Diving In - Viewing & Creating Specialties

For the /v1/custom/specialties endpoint, you can make either GET or POST requests.

We make a GET request to get a paginated list of all the specialties available.

We make a POST request to create a new specialties if we do not see the one we are looking for yet.

An example of a standard request, looking for Endocrinologist, would be as follows (notice that search is set to Endo):

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

We'll see our response:

{
    "count": 4,
    "next": null,
    "previous": null,
    "results": [
        {
            "uuid": "aff0d1a2-5fbe-41cb-a854-270c03528a43",
            "taxonomy_code": "207RE0101X",
            "provider_name": "Endocrinologist",
            "colloquial": "Hormone Doctor",
            "taxonomy_1": "Allopathic & Osteopathic Physicians",
            "taxonomy_2": "Internal Medicine",
            "taxonomy_3": "Endocrinology, Diabetes & Metabolism",
            "display": "Endocrinologist (Hormone Doctor)"
        },
        {
            "uuid": "b9531131-a91c-4e0e-98df-1ea88d759b2b",
            "taxonomy_code": "1223E0200X",
            "provider_name": "Endodontist",
            "colloquial": null,
            "taxonomy_1": "Dental Providers",
            "taxonomy_2": "Dentist",
            "taxonomy_3": "Endodontics",
            "display": "Endodontist"
        },
        {
            "uuid": "85b9d5d0-0f91-4b12-86e1-3c0d57e1cb06",
            "taxonomy_code": "2080P0205X",
            "provider_name": "Pediatric Endocrynologist",
            "colloquial": "Children & Adolescent Hormone Doctor",
            "taxonomy_1": "Allopathic & Osteopathic Physicians",
            "taxonomy_2": "Pediatrics",
            "taxonomy_3": "Pediatric Endocrinology",
            "display": "Pediatric Endocrynologist (Children & Adolescent Hormone Doctor)"
        },
        {
            "uuid": "1ed99e84-0769-4cd2-b2c3-b4e9800045b3",
            "taxonomy_code": "207VE0102X",
            "provider_name": "Reproductive Endocrynologist",
            "colloquial": "Women's Reproductive Health & Pregnancy Hormone Doctor",
            "taxonomy_1": "Allopathic & Osteopathic Physicians",
            "taxonomy_2": "Obstetrics & Gynecology",
            "taxonomy_3": "Reproductive Endocrinology",
            "display": "Reproductive Endocrynologist (Women's Reproductive Health & Pregnancy Hormone Doctor)"
        }
    ]
}

Now, let's say that we want to deviate from the 476 specialties we offer. For example, let's say that between an Internal Medicine Doctor, Family Medicine and General Practitioner, you want to create an overarching category called Primary Care Doctor. We could simply make a POST request to this endpoint, like so:

curl -X POST \
  'http://api.ribbonhealth.com/v1/custom/specialties' \
  -H 'Authorization: Token <>' \
  -d '{
    "display": "Primary Care Doctor (PCP)"
}'

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

{
    "data": {
        "uuid": "aab7cc3b-bf42-4fce-9e45-03fbc807992d",
        "taxonomy_code": "",
        "board_specialty": "",
        "board_sub_specialty": "",
        "non_md_specialty": "",
        "non_md_sub_specialty": "",
        "provider_name": "",
        "colloquial": "",
        "display": "Primary Care Doctor (PCP)",
        "taxonomy_1": "",
        "taxonomy_2": "",
        "taxonomy_3": ""
    }
}

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 \
  http://api.ribbonhealth.com/v1/custom/specialties/813c684e-bcb1-4a51-98a2-dc2f8a64871b \
  -H 'Authorization: Token <your token>' \
  -d '{
    "taxonomy_code": "",
    "board_specialty": "",
    "board_sub_specialty": "",
    "non_md_specialty": "",
    "non_md_sub_specialty": "",
    "provider_name": "",
    "colloquial": "",
    "display": "Primary Care Doctor",
    "taxonomy_1": "",
    "taxonomy_2": "",
    "taxonomy_3": ""
}'

Upon success, this will update the record! Please note, you need all of the above fields to submit a PUT request.

🚧

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!

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

curl -X DELETE \
  http://api.ribbonhealth.com/v1/custom/specialties/aab7cc3b-bf42-4fce-9e45-03fbc807992d \
  -H 'Authorization: Token <your token>'

❗️

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!