Overview

Description: This endpoint allows you to search through provider types that exist within the Ribbon API. You can also use this endpoint to create and edit your own provider types.

Endpoints:
Standard Index: /v1/provider_types
Custom Index: /v1/custom/provider_types and /v1/custom/provider_types/{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 types (e.g., Doctor, Dental Providers), which you power through GET requests to this endpoint.

Diving In - Searching & Viewing Provider Types

To retrieve all provider types, you can use GET requests to the standard index.

curl -X GET \
  'https://api.ribbonhealth.com/v1/provider_types' \
  -H 'authorization: Token <your_token>'

And we'll see all available provider types:

{
    "count": 23,
    "data": [
        {
            "uuid": "edeb875a-494a-4907-babb-5377ef1f49f9",
            "display_name": "Behavioral Health and Social Services"
        },
        {
            "uuid": "d94c8a5c-08dd-443a-9a99-a423c3d05cec",
            "display_name": "Chiropractic Providers"
        },
        {
            "uuid": "dc1a60bf-ed49-4242-8781-a4f6468260ed",
            "display_name": "Dental Providers"
        },
        ... 
    ]
}

Add the "search" parameter to search for specific provider type(s):

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

We'll see our response:

{
    "count": 2,
    "data": [
        {
            "uuid": "854a242b-9fa6-4427-b36f-ae7ba858e2c8",
            "display_name": "Pediatrician"
        },
        {
            "uuid": "0277098b-4c95-4a7b-8146-b89f12c87adc",
            "display_name": "Podiatrist"
        }
    ]
}

Diving In - Creating New Provider Types

Now, let's say that you want to introduce a new provider type to a provider or specialty. You will be required to add your new provider type to this reference endpoint before adding to a specific provider.

For instance, let's say that we want to designate certain providers as midwives. We could simply make a POST request to this endpoint, like so:

curl -X POST \
  'http://api.ribbonhealth.com/v1/custom/provider_types' \
  -H 'Authorization: Token <>' \
  -d '{
    "display_name": "Midwife"
}'

When the provider type has been created, we'll get back a valid response:

{
    "data": {
        "uuid": "cb239e62-7dd1-4984-af4d-82ea46cb1d9c",
        "display_name": "Midwife"
    }
}

We can now add this provider type to any doctor via the /v1/custom/providers/{NPI} endpoint or to any specialty via the /v1/custom/specialties/{uuid} endpoint using its display_name!

For example:

curl -X PUT \
  'http://api.ribbonhealth.com/v1/custom/providers/1942527510' \
  -H 'Authorization: Token <>' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider_types": ["Midwife", "Nursing"]
}'

If we didn't do this correctly and now want to edit or delete this custom provider type, keep reading to learn how to edit and delete!

Diving In - Editing & Deleting Provider Types

We can edit a custom provider type with a PUT request at /v1/custom/provider_types/{UUID}:

curl -X PUT \
  http://api.ribbonhealth.com/v1/custom/provider_types/cb239e62-7dd1-4984-af4d-82ea46cb1d9c \
  -H 'Authorization: Token <your token>' \
  -d '{
    "display_name": "Certified Nurse Midwife"
}'

Upon success, this will update the record!

{
    "data": {
        "uuid": "cb239e62-7dd1-4984-af4d-82ea46cb1d9c",
        "display_name": "Certified Nurse Midwife"
    }
}

Now, perhaps our data has changed and we want to remove a provider type altogether. We can merely submit a DELETE request to the /v1/custom/provider_types/{UUID} endpoint, like so:

curl -X DELETE \
  http://api.ribbonhealth.com/v1/custom/provider_types/cb239e62-7dd1-4984-af4d-82ea46cb1d9c \
  -H 'Authorization: Token <your token>'

🚧

You can only edit and delete custom provider types

You cannot edit or delete the provider types that Ribbon provides.

❗️

Edits and deletions will not propagate beyond the provider types list

When you edit or delete a custom provider type, the provider type will NOT be updated or removed, respectively, on any providers or specialties that it is attached to.

We hope to support this bulk update/remove functionality in the future!