API

Contacts API

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

Search Contacts

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

Requires contacts:read.

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

{
  "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.