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:
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}
.
The following use cases are supported:
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.
The following use cases are supported:
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.
The following use cases are supported:
Donation options contain additional fields for linking to MealConnect, and for storing contact info and other details about the donation partner.
https://boss-test.smarterx.com
Gets all donation options available to a customer. This includes options that are not enabled at any location.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
page
page_size
order
Sort results by the specified field, in the given direction (<field>_<direction>
).
name_asc
name_desc
category_asc
category_desc
state_asc
state_desc
street_address_asc
name
Search using name. Wildcards (*
) are supported.
description
Search using description. Wildcards (*
) are supported.
street_address
Search using street address. Wildcards (*
) are supported.
city
Search using city. Wildcards (*
) are supported.
state
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
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
Whether to include discarded locations in the response. If false, only non-discarded locations will be returned.
1
Create a new donation option
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
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.
1
{
"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 details for a single donation option
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
option_id
UUID of the option. This option must be previously registered with SmarterX.
1
Update a donation option (replaces option info)
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
option_id
UUID of the option. This option must be previously registered with SmarterX.
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.
1
{
"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
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
option_id
UUID of the option. This option must be previously registered with SmarterX.
Data to PATCH (partially update) a single donation option. May provide all or a subset of fields for update.
Unnamed Property
1
{
"description": "Austin area food bank",
"tax_id": "11-2345678",
"street_address": "12345 WEST BLVD",
"poc_name": "John Doe"
}
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}
.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
option_id
UUID of the option. This option must be previously registered with SmarterX.
1
Get locations
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
page
page_size
order
Sort results by the specified field, in the given direction (<field>_<direction>
).
name_asc
name_desc
category_asc
category_desc
state_asc
state_desc
street_address_asc
name
Search using name. Wildcards (*
) are supported.
description
Search using description. Wildcards (*
) are supported.
street_address
Search using street address. Wildcards (*
) are supported.
city
Search using city. Wildcards (*
) are supported.
state
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
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
Whether to include discarded locations in the response. If false, only non-discarded locations will be returned.
1
Create a new location
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
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
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.
1
{
"name": "austin-TX-681",
"description": "Free-form description",
"state": "TX",
"city": "Austin",
"street_address": "10401 RESEARCH BLVD",
"zip": "73301"
}
Get a details for a single location
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
options
Whether to include options in the response. If false, only location info will be returned.
location_name
Customer provided, unique name for a location. This location name must be previously registered with SmarterX.
1
Update a location (replaces location info)
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_name
Customer provided, unique name for a location. This location name must be previously registered with SmarterX.
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
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.
1
{
"name": "austin-TX-681",
"description": "Free-form description",
"state": "TX",
"city": "Austin",
"street_address": "10401 RESEARCH BLVD",
"zip": "73301"
}
Update a location
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_name
Customer provided, unique name for a location. This location name must be previously registered with SmarterX.
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
1
{
"description": "Free-form description",
"street_address": "10401 RESEARCH BLVD",
"zip": "73301"
}
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}
.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_name
Customer provided, unique name for a location. This location name must be previously registered with SmarterX.
1
Gets all binning options enabled available at a particular location. Returns 404 if the location isn't found.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
page
page_size
order
Sort results by the specified field, in the given direction (<field>_<direction>
).
name_asc
name_desc
category_asc
category_desc
state_asc
state_desc
street_address_asc
name
Search using name. Wildcards (*
) are supported.
description
Search using description. Wildcards (*
) are supported.
category
Search using category. Must use one of the allowed values.
disposal
donation
organics
recycle
vendor_managed
location_name
Customer provided, unique name for a location. This location name must be previously registered with SmarterX.
1
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.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_name
Customer provided, unique name for a location. This location name must be previously registered with SmarterX.
List of option_ids, used when bulk-enabling or disabling options at a single location.
option_ids
1
{
"option_ids": [
"580a921b-9493-823c-4098-592567755fd5",
"7404f941-47af-2ee4-39b6-510697e4fc18",
"1f238f4a-e947-a079-3215-4c554fa765cc"
]
}
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.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_name
Customer provided, unique name for a location. This location name must be previously registered with SmarterX.
List of option_ids, used when bulk-enabling or disabling options at a single location.
option_ids
1
{
"option_ids": [
"580a921b-9493-823c-4098-592567755fd5",
"7404f941-47af-2ee4-39b6-510697e4fc18",
"1f238f4a-e947-a079-3215-4c554fa765cc"
]
}
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.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_name
Customer provided, unique name for a location. This location name must be previously registered with SmarterX.
List of option_ids, used when bulk-enabling or disabling options at a single location.
option_ids
1
{
"option_ids": [
"580a921b-9493-823c-4098-592567755fd5",
"7404f941-47af-2ee4-39b6-510697e4fc18",
"1f238f4a-e947-a079-3215-4c554fa765cc"
]
}
Gets whether an option is enabled at a particular location. Returns 404 if the location or option isn't found.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_name
Customer provided, unique name for a location. This location name must be previously registered with SmarterX.
option_id
UUID of the option. This option must be previously registered with SmarterX.
1
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_name
Customer provided, unique name for a location. This location name must be previously registered with SmarterX.
option_id
UUID of the option. This option must be previously registered with SmarterX.
1
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
location_name
Customer provided, unique name for a location. This location name must be previously registered with SmarterX.
option_id
UUID of the option. This option must be previously registered with SmarterX.
1
Gets all binning options available to a customer. This includes options that are not enabled at any location.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
page
page_size
order
Sort results by the specified field, in the given direction (<field>_<direction>
).
name_asc
name_desc
category_asc
category_desc
state_asc
state_desc
street_address_asc
name
Search using name. Wildcards (*
) are supported.
description
Search using description. Wildcards (*
) are supported.
category
Search using category. Must use one of the allowed values.
disposal
donation
organics
recycle
vendor_managed
discarded
Whether to include discarded locations in the response. If false, only non-discarded locations will be returned.
1
Get a details for a single option
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
option_id
UUID of the option. This option must be previously registered with SmarterX.
1
Update an option
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
option_id
UUID of the option. This option must be previously registered with SmarterX.
Data to PATCH (partially update) a single sorting option. Only name/description updates are accepted.
Unnamed Property
1
{
"description": "Bin for acids"
}
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.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
option_id
UUID of the option. This option must be previously registered with SmarterX.
List of location names, used when bulk-enabling or disabling an option for multiple locations.
location_names
1
{}
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.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
option_id
UUID of the option. This option must be previously registered with SmarterX.
List of location names, used when bulk-enabling or disabling an option for multiple locations.
location_names
1
{}
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.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
option_id
UUID of the option. This option must be previously registered with SmarterX.
List of location names, used when bulk-enabling or disabling an option for multiple locations.
location_names
1
{}
Gets all locations where a particular option is enabled. Returns 404 if the option isn't found.
Authorization
The Authorization
header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE
.
page
page_size
order
Sort results by the specified field, in the given direction (<field>_<direction>
).
name_asc
name_desc
category_asc
category_desc
state_asc
state_desc
street_address_asc
name
Search using name. Wildcards (*
) are supported.
description
Search using description. Wildcards (*
) are supported.
street_address
Search using street address. Wildcards (*
) are supported.
city
Search using city. Wildcards (*
) are supported.
state
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
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
Whether to include discarded locations in the response. If false, only non-discarded locations will be returned.
option_id
UUID of the option. This option must be previously registered with SmarterX.
1