Copy page

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 or the staging portal 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:

Code
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, or individually 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 or in bulk, 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.

Code
{
  "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. 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

Code
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'

Code
{
  "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.