# findContacts

Fuzzy-search contacts by name, phone, email, or address. A phone may be its last four digits ("0142"). ARCHIVED contacts are included, marked `isArchived` (includeArchived: false drops them): one is still in the workspace, never "not in your contacts"; before a write, ask (a form): restore (unarchiveContacts), write anyway, or skip. Rows are QUALIFYING CANDIDATES, relevance-ranked, not matches: each leg (name, phone, email, address) keeps a row only if it clears a trigram-similarity threshold, and survivors are ranked by match quality, not raw score. So an empty result means nothing cleared the bar, and the top row is "the best that did", not the record you named. One shared word clears it: "Northgate Holdings" with no Northgate returns "McNeil Holdings" as totalCount 1. A single result is not evidence of certainty. Before using a contactId in a WRITE, check personName against the name the user said. If it differs, ask which contact they meant rather than write to the best guess: offer the near match as an ASK_USER_QUESTIONS choice naming that person; if you do write, report the name the write echoes, not the one you searched for (see addContactNote).

- Call: `POST https://server.goliathdata.com/api/v1/call` with `{ "operationId": "findContacts", "variables": {...} }`
- Scope: `READ`
- Type: query
- Idempotency: a read; rejects `Idempotency-Key`
- Rate-limited: no
- Result cap: `limit` is clamped to 50, without an error

## Variables

- `searchTerm`: `String!` (required)
- `limit`: `Int` (default `20`)
- `offset`: `Int` (default `0`)
- `includeArchived`: `Boolean` (default `true`)

## Response (data, an example)

```json
{
  "contactQuery": {
    "getContactIdentityResults": {
      "results": [
        {
          "contactId": "<ID>",
          "personName": "…",
          "propertyAddress": "…",
          "phoneNumber": "…",
          "email": "…",
          "isArchived": true
        }
      ],
      "totalCount": 0,
      "hasMore": true
    }
  }
}
```

## Example

```bash
curl https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer $GOLIATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "findContacts",
    "variables": {
      "searchTerm": "<String>"
    }
  }'
```