Search

Use search to resolve ambiguous ShelfCycle records before any write or exact detail read. 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, purchase_order, location.
`limit`	Optional result count from 1 to 20. Default is 10.

Unknown query parameters are rejected. Use types, not type. In v1.20, validation errors can return repair metadata such as suggestedAction: "replace_param" and validValues.types so clients can correct the next request without guessing.

Request

curl "$SHELFCYCLE_API_BASE_URL/search?q=Northstar&types=customer,contact,purchase_order&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", "purchase_order"],
    "rankingIsContractual": false,
    "truncated": false,
    "durationMs": 24
  }
}

matchedFields explains why a card matched. Use it before selecting the exact {type,id} for a write.

Information

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

What search does not return

Search cards never include money, line items, costs, attached files, inventory, lots, margin, accounting, or arbitrary hidden fields. Use exact detail or parent-scoped document endpoints after the workflow selects one id.

Next step after search

Use the selected card type to choose a detail endpoint:

customer        GET /customers/{id}
supplier        GET /suppliers/{id}
contact         GET /contacts/{id}
product         GET /products/{id}
order           GET /orders/{id}
purchase_order  GET /purchase-orders/{id}
location        GET /customers/{id}/locations/{locationId}
documents       GET /{customers,suppliers,products}/{id}/documents

For typed lookup before detail, use finder endpoints such as GET /customers, GET /products, GET /orders, or GET /purchase-orders. Finders require narrowing criteria and are covered in the Finders guide.