# Product Directory

Find products and product families by regulatory identity or name.

Canonical HTML: https://developer.shelfcycle.com/guides/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](/guides/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`.

```text
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. |

```bash
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

```json
{
  "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`:

```bash
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.