# smarter-1 User Guide

smarter-1 takes your product catalog and generates actionable recommendations 
on potential regulatory hazards for handling your products in a safe, 
compliant manner, without requiring supplier registration or extensive 
proprietary data. 

Behind the scenes, our enrichment process can identify missing attributes from
vetted publicly available sources. From there, our experts leverage a suite of
machine learning tools and automation to deliver recommendations quickly, at 
scale. 

You can use this API to submit your product data and collect the results of our
analysis. All you need to get started is a UPC and Product Name. (If you have 
more data available we'll utilize it and/or return it back to you to aid your 
workflows, but anything else is always optional.)

Generally, the process is as follows:
1. **Upload your product catalog**: You can upload your product catalog as a
   bulk CSV, or individually product-by-product
2. **Check in on our progress**: Analysis can take a bit of time, but you can
   check in periodically (polling) on individual products or page through the
   results of your entire catalog
3. **Retrieve your results**: Once analysis is complete, you can retrieve the
   results individually or in bulk

# Setup

All authentication with the API is done using a bearer token. When you sign
into the [developer portal](https://api.smarterx.com/docs) or the [staging
portal](https://api.staging.smarterx.com/docs) using auth0 credentials, an
API key is generated for you. Provide this key in the `Authorization`
header of your requests to authenticate with the API:

```bash
curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  'https://api.staging.smarterx.com/classification/v1/products?page_size=50'
```

# Uploading Products

You can upload your product catalog as a 
[bulk CSV](https://api.staging.smarterx.com/docs/customer-classification-api-v1#bulk-upload-products),
or 
[individually](https://api.staging.smarterx.com/docs/customer-classification-api-v1#upsert-product-attributes-by-upc) 
product-by-product. At a minimum, you must provide the `name` and `upc`
attributes for each product. UPC is provided in the URL for a single product
upload, and as a column in the CSV for bulk uploads. You can also provide
any additional attributes you have available, such as `brand`, `description`,
etc. If certain attributes are provided, their values will appear in other parts of the SmarterSorting ecosystem, such as our UI, as well as enable us to provide the best possible classifications and user experiences. These attributes include:
* `upc` - Universal Product Code of the product (GTIN and EAN are also acceptable)
* `name` - The name of the product
* `brand` - The product's brand
* `supplier` - The supplier of the product
* `ingredients` - The ingredients which comprise the product (if applicable)
* `sds` - A URL for the Safety Data Sheet for the product (if applicable)
* `manual` - A URL for the user manual for the product (if applicable)
* `un38` - A URL for the UN38.3 testing report document for the product (if applicable)
* `battery_chemistry` - The battery chemistry of the product (if applicable)
* `size` - The size of the product, including unit of measure (if applicable)
* `form` - The form of the product (if applicable)
* `external_id` - An identifier for your product, such as an SKU or database ID, that you may use to search, filter or identify a product

# Polling and Retrieving Results

When looking up products, either
[individually by upc](https://api.staging.smarterx.com/docs/customer-classification-api-v1#lookup-product-by-upc)
or in
[bulk](https://api.staging.smarterx.com/docs/customer-classification-api-v1#retrieve-filtered-products),
you can check the `status` field to see if the product is still being processed.
The `status` field can have the following values:

- `PENDING`: indicates that a product has been received and is enqueued for regulatory evaluation
- `IN_REVIEW`: indicates that the product is currently in review by our regulatory experts
- `CLASSIFICATION_COMPLETE`: indicates that the product has been
  classified and classifications are ready for retrieval

Each product will contain `attributes` and `classifications` fields. The
`attributes` field contains useful attributes you provided in the upload, for
example `sku` or other internal identifiers, or product descriptions. The
`classifications` field contains the results of our analysis. Both lists
contain objects with `name` and `value` fields.

```json
{
  "attested": {
    "attested_by": "supplier_who_attested",
    "attested_timestamp": "2025-07-14T11:44:00.622Z",
    "is_attested": true
  },
  "attributes": [
    {
      "name": "BRAND_NAME",
      "value": "ACME"
    },
    {
      "name": "INGREDIENTS",
      "value": "water, oil, linalool, zinc"
    },
    {
      "name": "MERCH_CLASS",
      "value": "FRAGRANCE"
    },
    {
      "name": "MERCH_DEPARTMENT",
      "value": "WMNS FRAGRANCE"
    },
    {
      "name": "SKU",
      "value": "12345"
    },
    {
      "name": "external_id",
      "value": "12345"
    }
  ],
  "classifications": [
    {
      "name": "batt_cell_or_button_cell",
      "value": ""
    },
    {
      "name": "battery_chemistry",
      "value": ""
    },
    {
      "name": "battery_configuration",
      "value": ""
    },
    {
      "name": "battery_used_for_running_equipment",
      "value": ""
    },
    {
      "name": "contains_battery",
      "value": false
    },
    {
      "name": "dot_basic_description",
      "value": "UN1266, PERFUMERY PRODUCTS, 3, II"
    },
    {
      "name": "dot_exception_codes",
      "value": "173.150(g) - Exception for flammable retail products containing ethyl alcohol - no markings required"
    },
    {
      "name": "dot_hazard_class",
      "value": "3"
    },
    {
      "name": "dot_least_burden",
      "value": "EXCEPTIONS APPLY"
    },
    {
      "name": "dot_limited_quantity",
      "value": true
    },
    {
      "name": "dot_packing_group",
      "value": "II"
    },
    {
      "name": "dot_proper_shipping_name",
      "value": "PERFUMERY PRODUCTS"
    },
    {
      "name": "dot_special_permit",
      "value": ""
    },
    {
      "name": "dot_sub_hazard_class",
      "value": "N/A"
    },
    {
      "name": "dot_technical_name",
      "value": ""
    },
    {
      "name": "dot_un_number",
      "value": "UN1266"
    },
    {
      "name": "flash_point",
      "value": "65.3"
    },
    {
      "name": "flash_point_uom",
      "value": "F"
    },
    {
      "name": "form",
      "value": "LIQUID"
    },
    {
      "name": "iata_basic_description",
      "value": "UN1266, PERFUMERY PRODUCTS, 3, II"
    },
    {
      "name": "iata_exception_codes",
      "value": "ID8000 - Eligible for ID8000 consumer commodities exception"
    },
    {
      "name": "iata_hazard_class",
      "value": "3"
    },
    {
      "name": "iata_least_burden",
      "value": "LIMITED QUANTITY"
    },
    {
      "name": "iata_limited_quantity",
      "value": true
    },
    {
      "name": "iata_packing_group",
      "value": "II"
    },
    {
      "name": "iata_proper_shipping_name",
      "value": "PERFUMERY PRODUCTS"
    },
    {
      "name": "iata_sub_hazard_class",
      "value": "N/A"
    },
    {
      "name": "iata_technical_name",
      "value": ""
    },
    {
      "name": "iata_un_number",
      "value": "UN1266"
    },
    {
      "name": "ifc_codes",
      "value": "FLIB"
    },
    {
      "name": "imdg_basic_description",
      "value": "UN1266, PERFUMERY PRODUCTS, 3, II"
    },
    {
      "name": "imdg_exception_codes",
      "value": ""
    },
    {
      "name": "imdg_hazard_class",
      "value": "3"
    },
    {
      "name": "imdg_least_burden",
      "value": "LIMITED QUANTITY"
    },
    {
      "name": "imdg_limited_quantity",
      "value": true
    },
    {
      "name": "imdg_marine_pollutant",
      "value": false
    },
    {
      "name": "imdg_packing_group",
      "value": "II"
    },
    {
      "name": "imdg_proper_shipping_name",
      "value": "PERFUMERY PRODUCTS"
    },
    {
      "name": "imdg_sub_hazard_class",
      "value": "N/A"
    },
    {
      "name": "imdg_technical_name",
      "value": ""
    },
    {
      "name": "imdg_un_number",
      "value": "UN1266"
    },
    {
      "name": "is_multi_component",
      "value": false
    },
    {
      "name": "lithium_metal_weight",
      "value": ""
    },
    {
      "name": "lithium_metal_weight_uom",
      "value": ""
    },
    {
      "name": "lithium_watt_hrs",
      "value": ""
    },
    {
      "name": "nfpa_flammability",
      "value": "3"
    },
    {
      "name": "nfpa_health",
      "value": "2"
    },
    {
      "name": "nfpa_reactivity",
      "value": "0"
    },
    {
      "name": "nfpa_special",
      "value": ""
    },
    {
      "name": "ph_max",
      "value": ""
    },
    {
      "name": "ph_min",
      "value": ""
    },
    {
      "name": "product_itself_battery",
      "value": false
    },
    {
      "name": "scopes",
      "value": "formulated"
    },
    {
      "name": "sds_link",
      "value": "https://files.smartersorting.com/sds/view/identifier/filename.pdf"
    },
    {
      "name": "size_uom",
      "value": "OZ"
    },
    {
      "name": "total_number_of_batt_or_cells",
      "value": ""
    },
    {
      "name": "un38.3_document_link",
      "value": ""
    },
    {
      "name": "upc_size",
      "value": "1.7"
    },
    {
      "name": "waste_rcra_codes",
      "value": "D001"
    },
    {
      "name": "waste_state_codes",
      "value": "CA 331, WA WT02"
    },
    {
      "name": "weight_of_all_batts",
      "value": ""
    },
    {
      "name": "weight_of_all_batts_uom",
      "value": ""
    }
  ],
  "created_date": "2025-05-15T22:18:17.780Z",
  "last_updated_date": "2026-06-10T15:51:00.916Z",
  "product_name": "Acme Anvil",
  "status": "CLASSIFICATION_COMPLETE",
  "upc": "03345678901234"
}
```

## Paging Results in Bulk

Several query parameters are available to help you filter and page through the
products returned from the
[bulk endpoint](https://api.staging.smarterx.com/docs/customer-classification-api-v1#retrieve-filtered-products).
Available query parameters include:
- `start_date`: returns only products last updated after midnight (UTC) on the provided date
- `end_date`: returns only products last updated before midnight (UTC) on the provided date
- `statuses`: returns only products with the provided status values (JSON array)
- `page_size`: the number of products to return per page (default: 50)
- `page_token`: the page token to use for pagination (provided in the 
  `pagination.next_page_token` field of the response)

### Example: Retrieving Completed Products With Pagination
```bash
curl --request GET \
  --url 'https://api.staging.smarterx.com/classification/v1/products?statuses=%5B%22CLASSIFICATION_COMPLETE%22%5D&page_size=50' \
  --header 'Authorization: Bearer YOUR_KEY_HERE'
```
```json
{
  "pagination": {
    "total": 100,
    "next_page_token": "WyJoZWxsbyIsICJ3b3JsZCJd",
    "page_size": 1
  },
  "products": [
    {
      "attested": {
        "attested_by": "supplier_who_attested",
        "attested_timestamp": "2025-07-14T11:44:00.622Z",
        "is_attested": true
      },
      "attributes": [
        {
          "name": "BRAND_NAME",
          "value": "ACME"
        },
        {
          "name": "INGREDIENTS",
          "value": "water, oil, linalool, zinc"
        },
        {
          "name": "MERCH_CLASS",
          "value": "FRAGRANCE"
        },
        {
          "name": "MERCH_DEPARTMENT",
          "value": "WMNS FRAGRANCE"
        },
        {
          "name": "SKU",
          "value": "12345"
        },
        {
          "name": "external_id",
          "value": "12345"
        }
      ],
      "classifications": [
        {
          "name": "batt_cell_or_button_cell",
          "value": ""
        },
        {
          "name": "battery_chemistry",
          "value": ""
        },
        {
          "name": "battery_configuration",
          "value": ""
        },
        {
          "name": "battery_used_for_running_equipment",
          "value": ""
        },
        {
          "name": "contains_battery",
          "value": false
        },
        {
          "name": "dot_basic_description",
          "value": "UN1266, PERFUMERY PRODUCTS, 3, II"
        },
        {
          "name": "dot_exception_codes",
          "value": "173.150(g) - Exception for flammable retail products containing ethyl alcohol - no markings required"
        },
        {
          "name": "dot_hazard_class",
          "value": "3"
        },
        {
          "name": "dot_least_burden",
          "value": "EXCEPTIONS APPLY"
        },
        {
          "name": "dot_limited_quantity",
          "value": true
        },
        {
          "name": "dot_packing_group",
          "value": "II"
        },
        {
          "name": "dot_proper_shipping_name",
          "value": "PERFUMERY PRODUCTS"
        },
        {
          "name": "dot_special_permit",
          "value": ""
        },
        {
          "name": "dot_sub_hazard_class",
          "value": "N/A"
        },
        {
          "name": "dot_technical_name",
          "value": ""
        },
        {
          "name": "dot_un_number",
          "value": "UN1266"
        },
        {
          "name": "flash_point",
          "value": "65.3"
        },
        {
          "name": "flash_point_uom",
          "value": "F"
        },
        {
          "name": "form",
          "value": "LIQUID"
        },
        {
          "name": "iata_basic_description",
          "value": "UN1266, PERFUMERY PRODUCTS, 3, II"
        },
        {
          "name": "iata_exception_codes",
          "value": "ID8000 - Eligible for ID8000 consumer commodities exception"
        },
        {
          "name": "iata_hazard_class",
          "value": "3"
        },
        {
          "name": "iata_least_burden",
          "value": "LIMITED QUANTITY"
        },
        {
          "name": "iata_limited_quantity",
          "value": true
        },
        {
          "name": "iata_packing_group",
          "value": "II"
        },
        {
          "name": "iata_proper_shipping_name",
          "value": "PERFUMERY PRODUCTS"
        },
        {
          "name": "iata_sub_hazard_class",
          "value": "N/A"
        },
        {
          "name": "iata_technical_name",
          "value": ""
        },
        {
          "name": "iata_un_number",
          "value": "UN1266"
        },
        {
          "name": "ifc_codes",
          "value": "FLIB"
        },
        {
          "name": "imdg_basic_description",
          "value": "UN1266, PERFUMERY PRODUCTS, 3, II"
        },
        {
          "name": "imdg_exception_codes",
          "value": ""
        },
        {
          "name": "imdg_hazard_class",
          "value": "3"
        },
        {
          "name": "imdg_least_burden",
          "value": "LIMITED QUANTITY"
        },
        {
          "name": "imdg_limited_quantity",
          "value": true
        },
        {
          "name": "imdg_marine_pollutant",
          "value": false
        },
        {
          "name": "imdg_packing_group",
          "value": "II"
        },
        {
          "name": "imdg_proper_shipping_name",
          "value": "PERFUMERY PRODUCTS"
        },
        {
          "name": "imdg_sub_hazard_class",
          "value": "N/A"
        },
        {
          "name": "imdg_technical_name",
          "value": ""
        },
        {
          "name": "imdg_un_number",
          "value": "UN1266"
        },
        {
          "name": "is_multi_component",
          "value": false
        },
        {
          "name": "lithium_metal_weight",
          "value": ""
        },
        {
          "name": "lithium_metal_weight_uom",
          "value": ""
        },
        {
          "name": "lithium_watt_hrs",
          "value": ""
        },
        {
          "name": "nfpa_flammability",
          "value": "3"
        },
        {
          "name": "nfpa_health",
          "value": "2"
        },
        {
          "name": "nfpa_reactivity",
          "value": "0"
        },
        {
          "name": "nfpa_special",
          "value": ""
        },
        {
          "name": "ph_max",
          "value": ""
        },
        {
          "name": "ph_min",
          "value": ""
        },
        {
          "name": "product_itself_battery",
          "value": false
        },
        {
          "name": "scopes",
          "value": "formulated"
        },
        {
          "name": "sds_link",
          "value": "https://files.smartersorting.com/sds/view/identifier/filename.pdf"
        },
        {
          "name": "size_uom",
          "value": "OZ"
        },
        {
          "name": "total_number_of_batt_or_cells",
          "value": ""
        },
        {
          "name": "un38.3_document_link",
          "value": ""
        },
        {
          "name": "upc_size",
          "value": "1.7"
        },
        {
          "name": "waste_rcra_codes",
          "value": "D001"
        },
        {
          "name": "waste_state_codes",
          "value": "CA 331, WA WT02"
        },
        {
          "name": "weight_of_all_batts",
          "value": ""
        },
        {
          "name": "weight_of_all_batts_uom",
          "value": ""
        }
      ],
      "created_date": "2025-05-15T22:18:17.780Z",
      "last_updated_date": "2026-06-10T15:51:00.916Z",
      "product_name": "Acme Anvil",
      "status": "CLASSIFICATION_COMPLETE",
      "upc": "03345678901234"
    }
  ]
}
```

Later queries can use the `page_token` to page through the results. If you're
polling on an interval, you can use the `start_date` query parameter to only
return products that have been updated since the last time you checked, 
useful for checking in on the status of a product without having to page 
through all of the results again.