Search

Use search to resolve ShelfCycle records before any write. Search returns typed candidate cards, not raw ERP rows.

Endpoint

GET /search

Required scope:

search:read

Query parameters:

Parameter	Meaning
`q`	Required search string. Minimum 2 characters.
`types`	Optional comma list: customer, supplier, contact, product, order, location.
`limit`	Optional result count from 1 to 20. Default is 10.

Request

curl "$SHELFCYCLE_API_BASE_URL/search?q=Northstar&types=customer,contact&limit=10" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Email notes automation"

Response

{
  "data": [
    {
      "type": "contact",
      "id": "contact-id",
      "displayName": "Jordan Buyer",
      "subtitle": "Northstar Chemical | jordan@example.com | President",
      "url": "https://app.shelfcycle.com/org-northstar/customers/customer-id/contacts",
      "archived": false,
      "matchedFields": [
        { "field": "email", "label": "Email", "value": "jordan@example.com" },
        { "field": "parent.name", "label": "Customer", "value": "Northstar Chemical" }
      ],
      "parent": { "type": "customer", "id": "customer-id", "displayName": "Northstar Chemical" }
    }
  ],
  "meta": {
    "requestId": "request-id",
    "limit": 10,
    "types": ["customer", "contact"],
    "rankingIsContractual": false,
    "truncated": false,
    "durationMs": 24
  }
}

matchedFields explains why a card matched. Use it as evidence before asking a person to confirm the exact {type,id} for a write.

Information

Ranking is useful but not contractual. If meta.truncated is true, narrow the query before writing.

Safe detail reads

The search:read scope also allows safe read-only detail DTOs:

GET /customers/{id}
GET /suppliers/{id}
GET /products/{id}
GET /contacts/{id}

Customer detail includes identity fields, archived state, timestamps, primary location, locations, addresses, and contact summaries. It does not expose credit, accounting, margin, or internal workflow fields.

Supplier detail includes identity, contact, address, contacts, and ship-from locations. It does not expose tax, banking, credit, ledger, cost, or payment fields.

Product detail includes code, external id, CAS, package quantity, logistics, hazmat fields, product family, supplier, and packaging. It does not expose prices, costs, lots, inventory, margins, or order history.

Order cards

Order cards are read-only context. Do not send order records as note subjects, note links, or write targets in v1. If approved, include order context as plain text in a note body.