# Search

Resolve ambiguous records into typed candidate cards.

Canonical HTML: https://developer.shelfcycle.com/guides/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

```text
GET /search
```

Required scope:

```text
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.21, validation errors can return repair metadata such as `suggestedAction: "replace_param"` and `validValues.types` so clients can correct the next request without guessing.

## Request

```bash
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

```json
{
  "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:

```text
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.