# POST /search

**Resource:** [Universal Search](./search.md)  
**Scopes:** `contacts:read`, `companies:read`, `opportunities:read`  
**Write operation:** no

Universal fuzzy search across contacts, customers, and deals. Returns ranked results with entity_type, display_name, subtitle, and relevance rank. Exact substring matches rank highest (1.0), fuzzy matches rank by trigram similarity. Names support typo-tolerant matching; email and phone use exact substring matching.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `query` | body | string | yes | Search text -- matches names, emails, phone numbers across all entity types |
| `limit` | body | number | no | Max results (1-100, default 25) |

## Request example

```bash
curl -X POST \
  "https://api.trustpager.com/functions/v1/api/v1/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "Sarah", "limit": 10 }'
```

## Response example

```json
{
  "data": [
    {
      "entity_type": "contact",
      "entity_id": "a1b2c3d4-...",
      "display_name": "Sarah Johnson",
      "subtitle": "sarah@example.com",
      "rank": 1.0
    },
    {
      "entity_type": "customer",
      "entity_id": "e5f6a7b8-...",
      "display_name": "Sarah Johnson Ltd",
      "subtitle": "info@sarahjohnson.com.au",
      "rank": 0.85
    },
    {
      "entity_type": "deal",
      "entity_id": "c9d0e1f2-...",
      "display_name": "Website Redesign - Sarah Johnson",
      "subtitle": "open",
      "rank": 0.72
    }
  ],
  "meta": { "credits_remaining": 4500 }
}
```

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`