# Reference directory

Page active customer and supplier matching hints for local caches.

Canonical HTML: https://developer.shelfcycle.com/guides/reference-directory

Page active customer and supplier matching hints for local caches without turning finders into broad exports.

The reference directory helps trusted local tools recognize known customers and suppliers during email triage, intake review, and duplicate checks. It is a matching layer, not a profile export or write authorization surface.

## Endpoints

| Endpoint | Scope | Use it for |
| --- | --- | --- |
| `GET /reference/customers` | `company-reference:read` | Active customer matching hints. |
| `GET /reference/suppliers` | `company-reference:read` | Active supplier matching hints. |

The acting user must also have live customer or supplier view permission. `GET /me` reports `effectiveCapabilities.companyReference` so callers can check whether the active directory is usable before paging.

## Page active rows

```bash
curl "$SHELFCYCLE_API_BASE_URL/reference/customers?limit=250" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Inbox triage"
```

```json
{
  "data": [
    {
      "type": "customer",
      "id": "customer-id",
      "displayName": "Northstar Chemical",
      "externalId": "NS-CHEM",
      "alternateNames": ["Northstar Tampa"],
      "website": "northstar.example",
      "emailDomains": ["northstar.example"],
      "phone": "555-0200",
      "city": "Tampa",
      "state": "FL",
      "country": "USA",
      "status": "active",
      "updatedAt": "2026-06-16T12:00:00.000Z",
      "url": "https://app.shelfcycle.com/org-northstar/customers/customer-id"
    }
  ],
  "meta": {
    "requestId": "request-id",
    "mode": "active_reference_directory",
    "resource": "customers",
    "limit": 250,
    "hasMore": true,
    "truncated": true,
    "nextCursor": "opaque-cursor",
    "generatedAt": "2026-06-16T12:05:00.000Z",
    "sort": "id_asc",
    "filters": { "includeArchived": false }
  }
}
```

When `meta.hasMore` is true, request the next page with `cursor`.

```bash
curl "$SHELFCYCLE_API_BASE_URL/reference/customers?cursor=opaque-cursor&limit=250" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

## Supported parameters

| Parameter | Rule |
| --- | --- |
| `limit` | Optional page size. Maximum is 500. |
| `cursor` | Opaque continuation token returned by the previous page. |
| `includeArchived` | Omit it or pass `false`. Archived reference export is not supported in v1.21. |

Reference routes do not support `updatedSince`, `updatedAtFrom`, or incremental refresh in v1.21. Periodically repage the active directory, then fetch exact detail by id before writes or business decisions.

## Field boundaries

Reference rows can include stable ids, display names, external ids, alternate names, website hosts, email domains, one phone, city, state, country, active status, `updatedAt`, and a ShelfCycle URL.

They do not include contacts, notes, order history, products, prices, costs, margin, payment terms, credit limits, sales reps, tax ids, ledger ids, raw street addresses, ACH or bank data, accounting records, or arbitrary private metadata.

> **Guardrail**: Use reference rows as matching hints only. Always hydrate `GET /customers/{id}` or `GET /suppliers/{id}` before any write-readiness check, execution, or business decision.