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.
`nameQueries`	One to 50 names in one request. Repeat the parameter for each name. It cannot be combined with `nameQuery`.
`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.

Match a list of names

Use nameQueries when a connected workflow starts with several printed or imported product names. Each submitted name follows the same matching behavior as nameQuery, while the response keeps coverage for every name.

curl "$SHELFCYCLE_API_BASE_URL/product-directory?nameQueries=ATBS%2050&nameQueries=TOFA%20L-1&limit=100" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Product list matching"

Each product row includes matchedQueries, and response metadata includes:

nameQueryCounts with the complete matching count for each submitted name;
unmatchedQueries for submitted names with no match; and
complete to show whether the returned pages cover the full filtered result.

One product appears once even when it matches several submitted names. Use its matchedQueries to connect the product back to each source name. Product Directory searches organization-wide product and family names, codes, external IDs, and synonyms. Use Supplier History when the workflow also needs a selected supplier's own names and commercial context.

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.