Finders

Use narrowed root endpoints to find typed resources before fetching exact detail, order context, or attached documents.

Choose the lookup for the job

Use the narrowest directory or lookup that matches the information already available:

Company and product finders require a supported narrowing filter. Order finders accept exact identifiers, status, related records, product criteria, business-date windows, or last-updated windows. Opportunity finders support focused filtering or authorized browsing with signed continuation.

Use Entity Resolution for new single-record binding. Use Tags or Product Directory when the source information is an exact tag or product identifier. Use the reference directory when a local tool needs active customer/supplier hints for matching, and use a typed finder when the resource family and narrowing filters are already known. Existing connections can continue using search for broad discovery. Use detail and parent-scoped document endpoints only after selecting a visible record. Use reports for allowed aggregate rollups, not as substitutes for finders or detail reads.

Company and product finders

Optional limit caps response size. includeArchived is explicit; archived records are never write targets.

Active company reference directory

Reference directory rows are active-only and sorted by id_asc. They can include display names, external ids, alternate names, website hosts, email domains, one phone, city, state, country, status, updatedAt, and URL. They do not include contacts, notes, order history, products, prices, costs, margin, payment terms, tax, ledger, raw street addresses, or arbitrary private metadata.

The directory accepts limit, cursor, and explicit includeArchived=false.

curl "$SHELFCYCLE_API_BASE_URL/products?code=ACETONE-PAIL&limit=5" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"

Product payloads use supported catalog fields. Product.name is deprecated and is not exposed by the public API.

Opportunity finder

Use the opportunity finder for customer- and supplier-side pipeline work. It returns visible opportunity summaries with relationship, owner, product, status, estimate, and update context.

curl "$SHELFCYCLE_API_BASE_URL/opportunities?status=LEAD,IN_PROGRESS&assignedToId=user-id&sortDirection=desc&limit=50" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Opportunity follow-up"

Narrow with matching text in query, one or more status or assignedToId values, an exact customerId, supplierId, or productId, or an ISO timestamp range using createdFrom and createdTo. Sort by updatedAt in ascending or descending order.

The response includes meta.total for the complete visible result and a signed meta.nextCursor when more rows are available. Continue with the cursor by itself. Fetch GET /opportunities/{id} after selecting a row to review metadata and the latest timeline activity.

Commercial document finders

For exact identifier matching, sales-order orderNo, customerOrderNo, and externalId accept one value or as many as 25 comma-separated values. Purchase-order orderNo and externalId support the same batching. For example:

GET /orders?customerOrderNo=A,B,C&limit=5

Order finders return up to 25 rows and a signed nextCursor when more results are available. Continue with the cursor alone so the original filters, ordering, and snapshot stay together.

Use paired changedFrom and changedTo for a half-open last-updated range of up to 30 days. Finder metadata reports the ordering, snapshot time, returned row count, and continuation cursor.

Detail reads

After selecting an id, hydrate the exact record:

GET /customers/{id}
GET /suppliers/{id}
GET /products/{id}
GET /orders/{id}
GET /purchase-orders/{id}
GET /opportunities/{id}
GET /contacts/{id}
GET /notes/{id}
GET /customers/{id}/documents
GET /suppliers/{id}/documents
GET /products/{id}/documents

Detail and attached document responses provide the fields documented for the selected record. Sales- and purchase-order detail returns 100 lines by default, accepts lineLimit up to 500, and supports consistent continuation through lineCursor. Continue with lineCursor alone.