# Contacts API

> Search the Contacts that the team policy allows an API token to use.


## Search Contacts

```http
GET /v1/contacts?query=ada&limit=20
Authorization: Bearer <token>
```

Requires `contacts:read`.

```json
{
  "data": [
    {
      "id": "c12345678901234567890123",
      "name": "Ada Lovelace"
    }
  ],
  "page": {
    "next_cursor": null,
    "has_more": false
  }
}
```

`query` searches the encrypted recipient index by Contact name and address. By default, the response returns only the Contact's display name and stable ID. A token that also has `contacts:addresses:read` receives the exact associated addresses:

```json
{
  "id": "c12345678901234567890123",
  "name": "Ada Lovelace",
  "addresses": ["ada@example.com", "+14155550100"]
}
```

Search results include only Contacts allowed by the team policy. An unknown direct conversation or group never appears as a Contact.

`limit` defaults to 50 and accepts 1 through 100. Search requests do not use a cursor. Omit `query` to page through the accessible Contact directory with `cursor`.

