Edit a Provider's Specialties

Overview

Description: This endpoint allows you to add or delete specialties in a standardized way, using the specialty UUID

Endpoint: /v1/custom/providers/{npi}/specialties and /v1/custom/providers/{npi}/specialties/{uuid}

Status: Live

Methods: PUT

Example use-case: You learn that a doctor is an Emergency Medicine doctor, which means that she cannot be booked in the way other doctors can, so you decide to add a new specialty indicator to the doctor to signify this.

Adding/Removing Specialties to a Provider

You'll notice when hitting our v1/custom/providers endpoint that for every specialty a doctor has, we have a standard format, and each specialty has a uuid. We can see for this doctor, we have one specialty, Psychiatrist:

{
  "first_name": "Jane",
  "last_name": "Doe",
  "npi": "12345890",
  "specialties": [        {
            "uuid": "c741df78-8460-46f6-a2ce-93de36eb7205",
            "is_primary": false,
            "taxonomy_code": "2084P0800X",
            "provider_name": "Psychiatrist",
            "colloquial": null,
            "board_specialty": "Psychiatry",
            "board_sub_specialty": "None",
            "non_md_specialty": null,
            "non_md_sub_specialty": null,
            "taxonomy_1": "Allopathic & Osteopathic Physicians",
            "taxonomy_2": "Psychiatry & Neurology",
            "taxonomy_3": "Psychiatry",
            "display": "Psychiatrist"
        }],
...other fields...
}

Let's say that, by golly, we learn that Dr. Jane Doe has another specialty. She is not just a Psychiatrist but also a Neurologist, which from hitting the custom/specialties endpoint, we can see has a UUID of a77d23ba-29f1-4afd-a0c4-62d2f0444cf7. Exactly like insurances, we can add or remove specialties the same way:

{
  "add": ["a77d23ba-29f1-4afd-a0c4-62d2f0444cf7"], 
  "is_primary": false
}

We submit this to the v1/custom/providers/1234567890/specialties endpoint:

curl -X PUT \
  'https://api.ribobnhealth.com/v1/custom/providers/1234567890/specialties' \
  -H 'authorization: Bearer <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "add": ["a77d23ba-29f1-4afd-a0c4-62d2f0444cf7"], 
  "is_primary": false
}'

Once we submit that change, we'll see this result in the doctor immediately:

{
  "first_name": "Jane",
  "last_name": "Doe",
  "npi": "12345890",
  "specialties": [{
            "uuid": "a77d23ba-29f1-4afd-a0c4-62d2f0444cf7",
            "is_primary": false,
            "taxonomy_code": "2084N0400X",
            "provider_name": "Neurologist",
            "colloquial": "Brain, Spinal, And Nerve Doctor",
            "board_specialty": "Neurology",
            "board_sub_specialty": "None",
            "non_md_specialty": null,
            "non_md_sub_specialty": null,
            "taxonomy_1": "Allopathic & Osteopathic Physicians",
            "taxonomy_2": "Psychiatry & Neurology",
            "taxonomy_3": "Neurology",
            "display": "Neurologist (Brain, Spinal, And Nerve Doctor)"
        },
            {
            "uuid": "c741df78-8460-46f6-a2ce-93de36eb7205",
            "is_primary": false,
            "taxonomy_code": "2084P0800X",
            "provider_name": "Psychiatrist",
            "colloquial": null,
            "board_specialty": "Psychiatry",
            "board_sub_specialty": "None",
            "non_md_specialty": null,
            "non_md_sub_specialty": null,
            "taxonomy_1": "Allopathic & Osteopathic Physicians",
            "taxonomy_2": "Psychiatry & Neurology",
            "taxonomy_3": "Psychiatry",
            "display": "Psychiatrist"
        }],
...other fields...
}

🚧
Using the is_primary Field
Using add or override without is_primary field will set the given specialties as is_primary=false by default. Please note that add and remove cannot be used together if you are also passing in is_primary as one of the fields.

Setting a Primary Specialty for a Provider

Now let's say that we learn Dr. Jane Doe is actually spending the large majority of her clinical time as a neurologist. We want to set her primary specialty to be Neurology (UUID: a77d23ba-29f1-4afd-a0c4-62d2f0444cf7) so that when we do a provider search by primary specialty, Dr. Jane Doe will show up for neurologists.

To do so, we would submit the following request:

curl -X PUT \
  'https://api.ribobnhealth.com/v1/custom/providers/1234567890/specialties/a77d23ba-29f1-4afd-a0c4-62d2f0444cf7' \
  -H 'authorization: Bearer <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "is_primary": true
}'

Once we submit the change, you'll see that Neurology is now set to the primary specialty for Dr. Jane Doe. You can always downgrade a primary specialty to just another specialty on a Provider by submitting the same request as the example above, but with “is_primary”: False instead of True in the JSON body.

{
  "first_name": "Jane",
  "last_name": "Doe",
  "npi": "12345890",
  "specialties": [{
            "uuid": "a77d23ba-29f1-4afd-a0c4-62d2f0444cf7",
            "is_primary": true,
            "taxonomy_code": "2084N0400X",
            "provider_name": "Neurologist",
            "colloquial": "Brain, Spinal, And Nerve Doctor",
            "board_specialty": "Neurology",
            "board_sub_specialty": "None",
            "non_md_specialty": null,
            "non_md_sub_specialty": null,
            "taxonomy_1": "Allopathic & Osteopathic Physicians",
            "taxonomy_2": "Psychiatry & Neurology",
            "taxonomy_3": "Neurology",
            "display": "Neurologist (Brain, Spinal, And Nerve Doctor)"
        },
            {
            "uuid": "c741df78-8460-46f6-a2ce-93de36eb7205",
            "is_primary": false,
            "taxonomy_code": "2084P0800X",
            "provider_name": "Psychiatrist",
            "colloquial": null,
            "board_specialty": "Psychiatry",
            "board_sub_specialty": "None",
            "non_md_specialty": null,
            "non_md_sub_specialty": null,
            "taxonomy_1": "Allopathic & Osteopathic Physicians",
            "taxonomy_2": "Psychiatry & Neurology",
            "taxonomy_3": "Psychiatry",
            "display": "Psychiatrist"
        }],
...other fields...
}

Wrapping Up - Override

Like in v1/custom/providers/npi/1234567890/insurances, we can use the override parameter in the JSON schema to list all of the specialty UUIDs that should override all others for that doctor:

{
  "override": ["a77d23ba-29f1-4afd-a0c4-62d2f0444cf7"]
}

If we do not have the specialty you are looking for, have no fear! You can create new specialty objects at v1/custom/specialties and then link them to the appropriate provider.

Overview

Adding/Removing Specialties to a Provider

🚧Using the is_primary Field

Setting a Primary Specialty for a Provider

Wrapping Up - Override

🚧
Using the `is_primary` Field