# filterContacts

Run a contact filter and paginate the matches with limit/offset. Returns a page of contacts (name, tags, phones, emails, `doNotContact`, reason, date, linked `properties`: no getContact per row) plus total and hasMore. Pass EITHER filterId (a saved filter from listContactFilters) OR filterTree (saveFilter's filter-tree DSL; conditions key `fieldId`, not `field`) to run an UNSAVED tree: same path and totals, nothing saved. filterTree verifies a filter before creating it and settles what a condition does (fetch a record with no value for the field and see whether the tree returns it). NEVER save a filter to measure one; save only the one asked for. Sort with sort: { field, direction } (`ASC` / `DESC`); field is a CLOSED vocabulary: `NAME` (A-Z), `SELLER_INTENT_SCORE`, `LAST_COMMUNICATION`, `LAST_ACTIVITY`, `DIAL_ATTEMPTS` (org-wide dials), `MY_LAST_CALL`, `MY_LAST_TEXT`, `LAST_UPDATED`, `CREATED_AT`, `TASK_HIGHLIGHT`, `AUCTION_DATE` (earliest upcoming auction; none sort last). Any other field is silently IGNORED. `participants`: its assignees (REVOKED: no longer assigned).

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

## Variables

- `filterId`: `ID`
- `filterTree`: `JSON`
- `limit`: `Int` (default `25`)
- `offset`: `Int` (default `0`)
- `sort`: `Sort`
  - `field`: `String!` (required)
  - `direction`: `SortDirection!` (required, one of `ASC`, `DESC`)

## Response (data, an example)

```json
{
  "contactQuery": {
    "paginateContacts": {
      "items": [
        {
          "id": "<ID>",
          "name": "…",
          "sellerIntentScore": 0,
          "isArchived": true,
          "doNotContact": true,
          "doNotContactReason": "…",
          "doNotContactSetAt": "2026-01-01T00:00:00.000Z",
          "tags": [
            {
              "id": "<ID>",
              "name": "…"
            }
          ],
          "phoneNumbers": [
            {
              "phoneNumber": "…",
              "suppressedMediums": [
                "SMS"
              ]
            }
          ],
          "emails": [
            {
              "email": "…"
            }
          ],
          "participants": [
            {
              "status": "REVOKED",
              "user": {
                "firstName": "…",
                "lastName": "…"
              }
            }
          ],
          "properties": [
            {
              "propertyString": "…",
              "verificationStatus": "VERIFIED",
              "property": {
                "id": "<ID>"
              }
            }
          ]
        }
      ],
      "pagination": {
        "total": 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": "filterContacts",
    "variables": {}
  }'
```