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

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

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

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.20.

Reference routes do not support updatedSince, updatedAtFrom, or incremental refresh in v1.20. 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.