GuidesAPI ReferenceTry Ribbon!
Back to All

Introducing our updated Locations Endpoint

over 4 years ago by Sahil Sud

📘

API updates are incremental!

By adding the new request header (see section "Accessing the New Version" below) for this update, you will automatically include updates from past API versions (i.e. 2019-10-28).

Overview

We have released an update to the Ribbon API that includes significant improvements to our /locations/ endpoints.

This update primarily affects the /v1/custom/locations endpoint, however certain updates also affect /v1/locations.

The purpose of this overhaul of the /locations/ endpoint is ultimately to make it at feature parity with the /providers/ endpoint. Moving forward we hope to facilitate navigation to providers and locations seamlessly.

🚧

Based on a standard integration - we do not expect this update to be a breaking change

❗️

Once you are ready to switch to the latest version - please inform us

We will coordinate a migration of any updates/edits/deletions that you made in your old version of the /locations/ endpoint to your new updated version. During business hours this will take us ~1 hour.

New Features

Address & Name Uniqueness Constraint | Previously, locations were held unique at the "address" level, meaning that no two locations could share the same address. Moving forward, locations will be held unique at an "address" & "name" level, meaning that no two locations can share the same address AND name. However, moving forward two locations can share the same address.
Note: this means that it will be easier to accidentally create duplicate locations moving forward!

Insurances for Locations | In line with the /providers/ endpoint, you can now add (and remove) Ribbon "insurance" objects to locations at the /locations/ endpoint. This functionality parallels that of the /providers/ endpoint. The available insurance objects are the same as those for the /providers/ endpoint. For example:

curl -X PUT \
  https://api.ribbonhealth.com/v1/custom/locations/777b9fda-a9db-4990-bb71-f29e24d3be75/insurances \
  -H 'Authorization: Token insert-token-here' \
  -d '{
	"add": ["3ed5ced6-217e-4037-8784-fe5afad0879b"]
}'

Specialties for Locations | In line with the /providers/ endpoint, you can now add (and remove) Ribbon "specialty" objects to locations at the /locations/ endpoint. This functionality parallels that of the /providers/ endpoint. The available specialty objects are the same as those for the /providers/ endpoint, however we will be adding new location specific specialties as well. For example:

curl -X PUT \
  https://api.ribbonhealth.com/v1/custom/locations/777b9fda-a9db-4990-bb71-f29e24d3be75/specialties \
  -H 'Authorization: Token insert-token-here' \
  -d '{
	"add": ["3ed5ced6-217e-4037-8784-fe5afad0879b"],
  "remove": ["9c470211-e3ea-4963-9568-8d8e9b8f5c44"]
}'

Fuzzy Name Search | Leverage the "name" search parameter at the /locations/ endpoint for a true 'fuzzy' search experience. For example:

https://api.ribbonhealth.com/v1/custom/locations?name=MinuteeClinicc

Will still return all "MinuteClinic" locations.

Create Custom Search Parameters | Now you can not only create custom fields for locations, but you can create your own custom search parameters on those custom fields. For example, if you add a field called "preferred" and set it equal to "true" for preferred locations, you can then create a custom search parameter that will allow you to filter to only preferred locations within the /locations/ endpoint.

Bug Fixes

Locations Not Appearing In Search | Previously, certain locations would not appear in search results at the /locations/ endpoint because they did not have custom attributes associated with them. Moving forward, that will not be an issue - the notion of "core" locations has been dissolved and any locations that you have added to your index will be accessible via search.

Inability to Edit Fields of Certain Locations | Previously, certain locations were not editable. Moving forward, that will not be an issue - the notion of "core" locations has been dissolved and any locations that you have added to your index will be editable.

Accessing the New Version

To access this version (2019-11-19) add the following to your API request header:

Ribbon-Version: 2019-11-19

For example:

curl -X GET \
  https://api.ribbonhealth.com/v1/custom/locations \
  -H 'Authorization: Token {insert token here}' \
  -H 'Ribbon-Version: 2019-11-19' \

🚧

Add Ribbon-Version: 2019-11-19 to every request header or email [email protected]

After you complete testing with the updated version, feel free to let us know and will set your entire API to this version. Email us at [email protected]

Alternatively, you can add Ribbon-Version: 2019-11-19 to every request header.

Note: a user interface to toggle API versions is in the works!