Create New Locations

Overview

Description: This endpoint allows you to create new locations and facilities

Endpoints: /v1/custom/locations

Status: Live

Methods:POST, DELETE

Example use-case: You want to add new urgent care locations (or labs, imaging centers, therapy centers, etc.) to an area that are not yet included in the existing Ribbon locations listings.

Diving In

Let's start by adding an Urgent Care location (although you can add any location type by changing a single parameter value, details below)! Let's say that you have data that Concentra Urgent Care is at 7800 NW 25th St 4, Doral, FL 33122, an establishment that you know is an urgent care center. Include the following in the JSON body:

curl -X POST \
  'https://api.ribbonhealth.com/v1/custom/locations' \
  -H 'Authorization: Bearer <Your Token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Concentra Urgent Care", 
  "address": "6521 N Andrews Ave Fort Lauderdale FL 33309", 
  "location_types": ["Urgent Care"]
  }'

We get the following result:

"data": {
        "uuid": "505c50ac-647f-434e-9e2b-9ce8dae053ed",
        "name": "Concentra Urgent Care",
        "address": "6521 N Andrews Ave, Fort Lauderdale, FL 33309, US",
        "address_details": {
            "street": "6521 N Andrews Ave",
            "address_line_1": "6521 N Andrews Ave",
            "address_line_2": null,
            "city": "Fort Lauderdale",
            "state": "FL",
            "zip": "33309"
        },
        "latitude": 26.2077412,
        "longitude": -80.14759219999999,
        "google_maps_link": "https://www.google.com/maps/@26.2077412,-80.14759219999999?q=6521%20N%20Andrews%20Ave%2C%20Fort%20Lauderdale%2C%20FL%2033309%2C%20US",
        "location_types": [
            "Urgent Care"
        ],
        "insurances": [],
        "specialties": []
    }
}

The result above is a new location object at the given "address" with the specified "name" and "location_types".
Note: the address string passed into the API is automatically normalized and geocoded.

🚧

Multiple "location_types" with any values you want!

If you would like to add a new location that is not an urgent care center but is instead a diagnostic radiology center and a laboratory, you can set "location_types": ["Diagnostic Radiology","Laboratory"].

🚧

New feature in API Version ype": "dange

We have released a new feature that introduces data type validation to stock Ribbon Fields in API Version e" level",
. This validation applies when you create new locations.

For more information, please refer to this changelog.

❗️

Locations are held unique at an "address" & "name" level

This means that no two locations can share the same address AND name. However, two or more locations can share the same address.

Be careful of creating duplicate values (e.g. two objects at the same addresses with similar but not exactly the same name)!

If you do attempt to create an exact duplicate, your POST call will return a message indicating that the given location already exists. It will also include the UUID of the existing location, so you can use that if you would like to edit or add to the existing location.

Note - this uniqueness constraint went live in API Version 2019.11.19 (see here for details).

And of course, if we want to delete a location we created, we just use a DELETE method request:

curl -X DELETE \
  https://api.ribbonhealth.com/v1/custom/locations/505c50ac-647f-434e-9e2b-9ce8dae053ed \
  -H 'Authorization: Bearer <your token>' \
  -H 'Cache-Control: no-cache'