BOSS Location Management API

Manage locations and disposal for the Back of Store System, including available disposal, recycling, and donation options.

Unless otherwise noted, the following limits apply to fields in URL path and query params:

  • Date/time strings must be provided in ISO 8601 format. All values converted to UTC, no time zone info will be retained.
  • All string fields, path and query parameters are limited to 127 characters or fewer
  • All UUIDs are UUIDv4. These will be generated initially by SmarterX, and used in subsequent requests to identify options.

General Features

Endpoints that return a list of resources will include pagination info in the response body, and paging may be controlled with query parameters. These endpoints will also typically include query parameters to filter the list of items by name, description, location or other fields.

For items that support DELETE operations, these are considered "soft deletes" which will prevent the item from being returned in GET requests, but will not remove it from the database. The items may be restored by performing a PATCH with the body {"discarded": false}.

Location Management

The following use cases are supported:

  • Creating new locations
  • Updating existing locations
  • Removing locations
  • Retrieving one or more locations, with optional parameters to filter by name, description or location
  • Enabling or disabling single or multiple disposal options at a location

Note: API users are responsible for enforcing validity of options for a location. For example, assigning a State Toxic disposal option for a location in a state that does not have state-level regulations may result in undesirable recommendation results.

Option Management

The following use cases are supported:

  • Updating existing option names and descriptions
  • Retrieving one or more options, with optional parameters to filter by name, description, or category
  • Enabling or disabling an option for multiple locations
  • Removing options (soft delete)

With the exception of Donation Partners, new options must be created by SmarterX, since they often require new rule sets and other configuration behind the scenes to ensure proper bin results. Our future roadmap includes self-service rule writing for retail customers via Smarter-1, but this is out of scope for v1 of Location Management.

Donation Option Management

The following use cases are supported:

  • Creating new donation options
  • Updating existing donation options (names, descriptions, tax IDs, POC info, etc.)
  • Retrieving one or more donation options, with optional parameters to filter by name, description, or location
  • Removing donation options (soft delete)

Donation options contain additional fields for linking to MealConnect, and for storing contact info and other details about the donation partner.

BASE URL
https://boss-test.smarterx.com

Get all donation options

Gets all donation options available to a customer. This includes options that are not enabled at any location.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Query Parameters

page

optional, integer, default: 1, minimum value of 1

page_size

optional, integer, default: 100, maximum value of 1000, minimum value of 1

order

optional, string enum

Sort results by the specified field, in the given direction (<field>_<direction>).

Possible Enum Values

name_asc

name_desc

category_asc

category_desc

state_asc

state_desc

street_address_asc

name

optional, string

Search using name. Wildcards (*) are supported.

description

optional, string

Search using description. Wildcards (*) are supported.

street_address

optional, string

Search using street address. Wildcards (*) are supported.

city

optional, string

Search using city. Wildcards (*) are supported.

state

optional, string

Search using state. Use commas or spaces to separate multiple states in a list, the search will return locations in any of the listed states.

zip

optional, string

Search using zip. Use commas or spaces to separate multiple zip codes in a list, the search will return locations in any of the listed zip codes.

discarded

optional, boolean, default: false

Whether to include discarded locations in the response. If false, only non-discarded locations will be returned.

GET
/v1/boss/donation_options
1

Create a new donation option

Create a new donation option

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Request Body

Data for a single donation option. These are the fields required to create a new donation option, or perform a PUT to update an existing donation option.

Unnamed Property

Data for a single donation option. These are the fields required to create a new donation option, or perform a PUT to update an existing donation option.

POST
/v1/boss/donation_options
1
EXAMPLE BODY
{
  "name": "Food bank #1",
  "description": "Austin area food bank",
  "tax_id": "11-2345678",
  "state": "TX",
  "city": "Austin",
  "street_address": "12345 WEST BLVD",
  "zip": "73301",
  "mealconnect": true,
  "poc_name": "John Doe",
  "poc_email": "jdoe@example.org",
  "poc_phone": "512-555-1234"
}

Get a single donation option

Get a details for a single donation option

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

option_id

required, string

UUID of the option. This option must be previously registered with SmarterX.

GET
/v1/boss/donation_options/:option_id
1

Update a donation option

Update a donation option (replaces option info)

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

option_id

required, string

UUID of the option. This option must be previously registered with SmarterX.

Request Body

Data for a single donation option. These are the fields required to create a new donation option, or perform a PUT to update an existing donation option.

Unnamed Property

Data for a single donation option. These are the fields required to create a new donation option, or perform a PUT to update an existing donation option.

PUT
/v1/boss/donation_options/:option_id
1
EXAMPLE BODY
{
  "name": "Food bank #1",
  "description": "Austin area food bank",
  "tax_id": "11-2345678",
  "state": "TX",
  "city": "Austin",
  "street_address": "12345 WEST BLVD",
  "zip": "73301",
  "mealconnect": true,
  "poc_name": "John Doe",
  "poc_email": "jdoe@example.org",
  "poc_phone": "512-555-1234"
}

Update a donation option

Update a donation option

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

option_id

required, string

UUID of the option. This option must be previously registered with SmarterX.

Request Body

Data to PATCH (partially update) a single donation option. May provide all or a subset of fields for update.

Unnamed Property
PATCH
/v1/boss/donation_options/:option_id
1
EXAMPLE BODY
{
  "description": "Austin area food bank",
  "tax_id": "11-2345678",
  "street_address": "12345 WEST BLVD",
  "poc_name": "John Doe"
}

Soft-delete a donation option

Soft-delete a donation option. This will prevent the option from being returned in GET requests, but will not remove it from the database. The option may be restored by performing a PATCH with the body {"discarded": false}.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

option_id

required, string

UUID of the option. This option must be previously registered with SmarterX.

DELETE
/v1/boss/donation_options/:option_id
1

Get locations for a customer

Get locations

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Query Parameters

page

optional, integer, default: 1, minimum value of 1

page_size

optional, integer, default: 100, maximum value of 1000, minimum value of 1

order

optional, string enum

Sort results by the specified field, in the given direction (<field>_<direction>).

Possible Enum Values

name_asc

name_desc

category_asc

category_desc

state_asc

state_desc

street_address_asc

name

optional, string

Search using name. Wildcards (*) are supported.

description

optional, string

Search using description. Wildcards (*) are supported.

street_address

optional, string

Search using street address. Wildcards (*) are supported.

city

optional, string

Search using city. Wildcards (*) are supported.

state

optional, string

Search using state. Use commas or spaces to separate multiple states in a list, the search will return locations in any of the listed states.

zip

optional, string

Search using zip. Use commas or spaces to separate multiple zip codes in a list, the search will return locations in any of the listed zip codes.

discarded

optional, boolean, default: false

Whether to include discarded locations in the response. If false, only non-discarded locations will be returned.

GET
/v1/boss/locations
1

Create a new location

Create a new location

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Request Body

Data for a single location, e.g. a physical store. These are the fields required to POST a new location, or PUT updated location info.

Unnamed Property

object

Data for a single location, e.g. a physical store. These are the fields required to POST a new location, or PUT updated location info.

POST
/v1/boss/locations
1
EXAMPLE BODY
{
  "name": "austin-TX-681",
  "description": "Free-form description",
  "state": "TX",
  "city": "Austin",
  "street_address": "10401 RESEARCH BLVD",
  "zip": "73301"
}

Get a single location

Get a details for a single location

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Query Parameters

options

optional, boolean, default: false

Whether to include options in the response. If false, only location info will be returned.

Path Parameters

location_name

required, string

Customer provided, unique name for a location. This location name must be previously registered with SmarterX.

GET
/v1/boss/locations/:location_name
1

Update a location

Update a location (replaces location info)

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_name

required, string

Customer provided, unique name for a location. This location name must be previously registered with SmarterX.

Request Body

Data for a single location, e.g. a physical store. These are the fields required to POST a new location, or PUT updated location info.

Unnamed Property

object

Data for a single location, e.g. a physical store. These are the fields required to POST a new location, or PUT updated location info.

PUT
/v1/boss/locations/:location_name
1
EXAMPLE BODY
{
  "name": "austin-TX-681",
  "description": "Free-form description",
  "state": "TX",
  "city": "Austin",
  "street_address": "10401 RESEARCH BLVD",
  "zip": "73301"
}

Update a location

Update a location

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_name

required, string

Customer provided, unique name for a location. This location name must be previously registered with SmarterX.

Request Body

Data for a single location, e.g. a physical store. These are the fields required to perform a PATCH to update an existing location.

Unnamed Property
PATCH
/v1/boss/locations/:location_name
1
EXAMPLE BODY
{
  "description": "Free-form description",
  "street_address": "10401 RESEARCH BLVD",
  "zip": "73301"
}

Soft-delete a location

Soft-delete a location. This will prevent the location from being returned in GET requests, but will not remove it from the database. The location may be restored by performing a PATCH with the body {"discarded": false}.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_name

required, string

Customer provided, unique name for a location. This location name must be previously registered with SmarterX.

DELETE
/v1/boss/locations/:location_name
1

Get enabled options for a location

Gets all binning options enabled available at a particular location. Returns 404 if the location isn't found.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Query Parameters

page

optional, integer, default: 1, minimum value of 1

page_size

optional, integer, default: 100, maximum value of 1000, minimum value of 1

order

optional, string enum

Sort results by the specified field, in the given direction (<field>_<direction>).

Possible Enum Values

name_asc

name_desc

category_asc

category_desc

state_asc

state_desc

street_address_asc

name

optional, string

Search using name. Wildcards (*) are supported.

description

optional, string

Search using description. Wildcards (*) are supported.

category

optional, string enum

Search using category. Must use one of the allowed values.

Possible Enum Values

disposal

donation

organics

recycle

vendor_managed

Path Parameters

location_name

required, string

Customer provided, unique name for a location. This location name must be previously registered with SmarterX.

GET
/v1/boss/locations/:location_name/options
1

Disable several options at a location

Disable several options at a location. Any options not included will not be modified. If the response is not a 204 (e.g. 400, 404), no options will be modified.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_name

required, string

Customer provided, unique name for a location. This location name must be previously registered with SmarterX.

Request Body

List of option_ids, used when bulk-enabling or disabling options at a single location.

option_ids

optional, array of strings
PATCH
/v1/boss/locations/:location_name/options/disabled
1
EXAMPLE BODY
{
  "option_ids": [
    "580a921b-9493-823c-4098-592567755fd5",
    "7404f941-47af-2ee4-39b6-510697e4fc18",
    "1f238f4a-e947-a079-3215-4c554fa765cc"
  ]
}

Enable only specified options at a location

Enable multiple options at a location. Any options not included in the request body will be disabled. If the response is not a 204 (e.g. 400, 404), no options will be modified.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_name

required, string

Customer provided, unique name for a location. This location name must be previously registered with SmarterX.

Request Body

List of option_ids, used when bulk-enabling or disabling options at a single location.

option_ids

optional, array of strings
PUT
/v1/boss/locations/:location_name/options/enabled
1
EXAMPLE BODY
{
  "option_ids": [
    "580a921b-9493-823c-4098-592567755fd5",
    "7404f941-47af-2ee4-39b6-510697e4fc18",
    "1f238f4a-e947-a079-3215-4c554fa765cc"
  ]
}

Enable several options at a location

Enable options at a location. Any options not included will not be modified. If the response is not a 204 (e.g. 400, 404), no options will be modified.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_name

required, string

Customer provided, unique name for a location. This location name must be previously registered with SmarterX.

Request Body

List of option_ids, used when bulk-enabling or disabling options at a single location.

option_ids

optional, array of strings
PATCH
/v1/boss/locations/:location_name/options/enabled
1
EXAMPLE BODY
{
  "option_ids": [
    "580a921b-9493-823c-4098-592567755fd5",
    "7404f941-47af-2ee4-39b6-510697e4fc18",
    "1f238f4a-e947-a079-3215-4c554fa765cc"
  ]
}

Get whether an option is enabled at a location

Gets whether an option is enabled at a particular location. Returns 404 if the location or option isn't found.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_name

required, string

Customer provided, unique name for a location. This location name must be previously registered with SmarterX.

option_id

required, string

UUID of the option. This option must be previously registered with SmarterX.

GET
/v1/boss/locations/:location_name/options/:option_id/enabled
1

Enable an option at a location

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_name

required, string

Customer provided, unique name for a location. This location name must be previously registered with SmarterX.

option_id

required, string

UUID of the option. This option must be previously registered with SmarterX.

PUT
/v1/boss/locations/:location_name/options/:option_id/enabled
1

Disable an option at a location

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

location_name

required, string

Customer provided, unique name for a location. This location name must be previously registered with SmarterX.

option_id

required, string

UUID of the option. This option must be previously registered with SmarterX.

DELETE
/v1/boss/locations/:location_name/options/:option_id/enabled
1

Get all options

Gets all binning options available to a customer. This includes options that are not enabled at any location.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Query Parameters

page

optional, integer, default: 1, minimum value of 1

page_size

optional, integer, default: 100, maximum value of 1000, minimum value of 1

order

optional, string enum

Sort results by the specified field, in the given direction (<field>_<direction>).

Possible Enum Values

name_asc

name_desc

category_asc

category_desc

state_asc

state_desc

street_address_asc

name

optional, string

Search using name. Wildcards (*) are supported.

description

optional, string

Search using description. Wildcards (*) are supported.

category

optional, string enum

Search using category. Must use one of the allowed values.

Possible Enum Values

disposal

donation

organics

recycle

vendor_managed

discarded

optional, boolean, default: false

Whether to include discarded locations in the response. If false, only non-discarded locations will be returned.

GET
/v1/boss/options
1

Get a single option

Get a details for a single option

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

option_id

required, string

UUID of the option. This option must be previously registered with SmarterX.

GET
/v1/boss/options/:option_id
1

Update an option

Update an option

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

option_id

required, string

UUID of the option. This option must be previously registered with SmarterX.

Request Body

Data to PATCH (partially update) a single sorting option. Only name/description updates are accepted.

Unnamed Property
PATCH
/v1/boss/options/:option_id
1
EXAMPLE BODY
{
  "description": "Bin for acids"
}

Disable an option at multiple locations

Disable an option at multiple locations. Any locations not included will not be modified. If the response is not a 204 (e.g. 400, 404), no locations will be modified.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

option_id

required, string

UUID of the option. This option must be previously registered with SmarterX.

Request Body

List of location names, used when bulk-enabling or disabling an option for multiple locations.

location_names

optional, array of strings
PATCH
/v1/boss/options/:option_id/locations/disabled
1
EXAMPLE BODY
{}

Enable an option only at specified locations

Enable an option at multiple locations. Any locations not included in the request body will have the option disabled. If the response is not a 204 (e.g. 400, 404), no locations will be modified.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

option_id

required, string

UUID of the option. This option must be previously registered with SmarterX.

Request Body

List of location names, used when bulk-enabling or disabling an option for multiple locations.

location_names

optional, array of strings
PUT
/v1/boss/options/:option_id/locations/enabled
1
EXAMPLE BODY
{}

Enable an option at multiple locations

Enable an option at multiple locations. Any locations not included will not be modified. If the response is not a 204 (e.g. 400, 404), no locations will be modified.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

option_id

required, string

UUID of the option. This option must be previously registered with SmarterX.

Request Body

List of location names, used when bulk-enabling or disabling an option for multiple locations.

location_names

optional, array of strings
PATCH
/v1/boss/options/:option_id/locations/enabled
1
EXAMPLE BODY
{}

Get locations for an option

Gets all locations where a particular option is enabled. Returns 404 if the option isn't found.

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Query Parameters

page

optional, integer, default: 1, minimum value of 1

page_size

optional, integer, default: 100, maximum value of 1000, minimum value of 1

order

optional, string enum

Sort results by the specified field, in the given direction (<field>_<direction>).

Possible Enum Values

name_asc

name_desc

category_asc

category_desc

state_asc

state_desc

street_address_asc

name

optional, string

Search using name. Wildcards (*) are supported.

description

optional, string

Search using description. Wildcards (*) are supported.

street_address

optional, string

Search using street address. Wildcards (*) are supported.

city

optional, string

Search using city. Wildcards (*) are supported.

state

optional, string

Search using state. Use commas or spaces to separate multiple states in a list, the search will return locations in any of the listed states.

zip

optional, string

Search using zip. Use commas or spaces to separate multiple zip codes in a list, the search will return locations in any of the listed zip codes.

discarded

optional, boolean, default: false

Whether to include discarded locations in the response. If false, only non-discarded locations will be returned.

Path Parameters

option_id

required, string

UUID of the option. This option must be previously registered with SmarterX.

GET
/v1/boss/options/:option_id/locations
1