Location Types Endpoint

Overview

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

Endpoints:
Standard Index: /v1/location_types
Custom Index: /v1/custom/location_types and /v1/custom/location_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 location types (e.g., Hospital, Urgent Care), which you power through GET requests to this endpoint.

Diving In - Searching & Viewing Location Types

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

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

And we'll see all available location types:

{
    "count": 42,
    "data": [
        {
            "uuid": "b5458763-968e-4690-bc70-f29d3a7459a9",
            "display_name": "Ambulatory Surgery Center"
        },
        {
            "uuid": "ce353de6-a20b-4283-9162-93b3b9be9570",
            "display_name": "Assisted Living Facility"
        },
        {
            "uuid": "6628f604-ef21-4cc0-bec8-b9641b4e5262",
            "display_name": "Clinic"
        },
        ... 
    ]
}

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

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

We'll see our response:

{
    "count": 7,
    "data": [
        {
            "uuid": "23d2210d-64b8-4c63-9429-61a3cadb8ad5",
            "display_name": "Clinic"
        },
        {
            "uuid": "910b33a4-3a41-4712-a1b7-5892d1ed27c8",
            "display_name": "Independent Clinic"
        },
        {
            "uuid": "8fe4b674-6a8a-462f-bd1f-799d271dd682",
            "display_name": "Primary Care Clinic"
        },
        ...
    ]
}

Diving In - Creating New Location Types

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

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

curl -X POST \
  'https://api.ribbonhealth.com/v1/custom/location_types' \
  -H 'Authorization: Bearer <your_token>' \
  -d '{
    "display_name": "Radiology"
}'

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

{
    "data": {
        "uuid": "cd7f242d-3016-4db6-94f4-77b8237127a3",
        "display_name": "Radiology"
    }
}

We can now add this location type to any location via the /v1/custom/locations/{uuid} or /v1/custom/providers/{npi}/locations/{uuid} endpoints using its display_name!

For example:

curl -X PUT \
  'https://api.ribbonhealth.com/v1/custom/locations/600fab02-dc15-426b-80ef-fa88c9852072' \
  -H 'Authorization: Bearer <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "location_types": ["Radiology"]
}'

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

Diving In - Editing & Deleting Location Types

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

curl -X PUT \
  https://api.ribbonhealth.com/v1/custom/location_types/cd7f242d-3016-4db6-94f4-77b8237127a3 \
  -H 'Authorization: Bearer <your token>' \
  -d '{
    "display_name": "Radiology - Diagnostic Imaging"
}'

Upon success, this will update the record!

{
    "data": {
        "uuid": "cd7f242d-3016-4db6-94f4-77b8237127a3",
        "display_name": "Radiology - Diagnostic Imaging"
    }
}

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

curl -X DELETE \
  https://api.ribbonhealth.com/v1/custom/location_types/cd7f242d-3016-4db6-94f4-77b8237127a3 \
  -H 'Authorization: Bearer <your token>'

🚧

You can only edit and delete custom location types

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

❗️

Edits and deletions will not propagate beyond the location types list

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

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