Product Directory

Find products and product families by regulatory identity or familiar name before selecting the exact record a workflow needs.

Use Product Directory for catalog discovery from UN/NA numbers, CAS numbers, hazard classes, packing groups, or names. Use Entity Resolution after discovery when the workflow must choose one authorized ID from business wording.

Access

The endpoint requires products:read plus the acting user's current Product access. GET /me reports the result through effectiveCapabilities.productDirectory.view.

GET /product-directory

Choose one or more filters

At least one discovery filter is required. When several are provided, a result must match all of them.

Parameter	Use it for
`unNumber`	A UN or NA transport number, such as `3077` or `UN 3077`.
`casNumber`	A CAS Registry Number.
`hazardClass`	A hazard class such as `3`, `6.1`, or `Class 9`.
`packingGroup`	Packing group `I`, `II`, or `III`; numeric forms 1, 2, and 3 are also accepted.
`nameQuery`	Two to 120 characters. Every searchable token must match a product or family name, code, external ID, or synonym.
`includeArchived`	Pass `true` to include archived products.
`limit`	Rows per page from 1 to 100. The default is 25.
`cursor`	The continuation value returned by the preceding page.

curl "$SHELFCYCLE_API_BASE_URL/product-directory?unNumber=3077&packingGroup=III&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Regulatory product intake"

Read the directory result

{
  "data": [
    {
      "entityClass": "product",
      "id": "product-id",
      "displayName": "CLEARWATER 742",
      "familyName": "Clearwater Treatment Products",
      "casNumber": "11104-30-0",
      "unNumber": "UN3077",
      "properShippingName": "ENVIRONMENTALLY HAZARDOUS SUBSTANCE, SOLID, N.O.S.",
      "hazardClass": "9",
      "packingGroup": "III",
      "matchBasis": "sku",
      "externalId": "CW-742",
      "archived": false
    }
  ],
  "meta": {
    "capabilityKey": "find_products",
    "capabilityVersion": "1.1.0",
    "returnedRecords": 1,
    "populationCount": 1,
    "complete": true,
    "hasMore": false,
    "nextCursor": null,
    "ordering": "display_name_entity_type_id",
    "currentState": true,
    "snapshotIsolatedAcrossRequests": false,
    "requestId": "request-id",
    "archivedExcluded": true,
    "searchedIdentifierSpaces": ["un_number", "packing_group"]
  }
}

entityClass distinguishes a product from a product_family. Regulatory fields travel with the result so a workflow can compare the identity it searched for before choosing a record.

For product rows, matchBasis reports whether a regulatory identifier matched the SKU directly or came from its family. Product-family rows use entityClass: "product_family". Hazard class and packing group apply to product records.

searchedIdentifierSpaces confirms which filter families shaped the result. archivedExcluded confirms whether the response is active-only.

Continue larger results

When meta.hasMore is true, repeat the original filters and limit, then add meta.nextCursor:

curl "$SHELFCYCLE_API_BASE_URL/product-directory?unNumber=3077&packingGroup=III&limit=25&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"

The cursor stays with the original filters, page size, organization, and key. populationCount becomes available when the final page completes the current result set. Restart from the original filters when refreshing the directory.

Choose the next endpoint

Use Product Directory to discover the authorized product and family population that carries one or more known identifiers.
Use Entity Resolution to turn familiar wording into one selected ID with clear unique, ambiguous, or no-match outcomes.
Use GET /products/{id} after selecting a product and GET /product-families/{id} after selecting a family when exact detail is needed.
Use a narrowed GET /products finder when the workflow already has an exact product code, external ID, supplier ID, or product search term.