Sign in

v1

latestOpenAPI 3.0.02026-07-26870415.2 KB
contacts

Search contacts

Find contacts by name, last name, email, phone number, WhatsApp number, or channel value. Use the returned contact ids with related endpoints like /v1/contacts/{id}/tickets and /v1/contacts/{id}/calls.

get/v1/contacts/search

Query parameters

workspace_idstring required

Workspace to query.

Example:j57demo8f8x7c9v0n2q4r6t8y1u3i5o
querystring required

Search value. Common lookups include email address, phone number, first name, and last name.

Example:joe@gmail.com
field'any' | 'name' | 'first_name' | 'last_name' | 'email' | 'phone' | 'whatsapp' | 'channel'

Field to search. any uses heuristics: email-like input searches channels, phone-like input searches phone channels, otherwise it searches contact metadata.

Example:email
limitinteger
cursorstring
archived'true' | 'false'
inbox_type_idstring

Response

Contact search results

next_cursorstring nullable required
has_moreboolean required

Example response

{
  "data": [
    {
      "id": "ph77c0dy0mgdpzmqz6tesry8w184002s",
      "workspace_id": "j57demo8f8x7c9v0n2q4r6t8y1u3i5o",
      "first_name": "Jane",
      "last_name": "Doe",
      "image_url": null,
      "type": null,
      "inbox_type_id": "guest",
      "archived": false,
      "ai_paused": false,
      "last_channel": "unthreaded_email",
      "last_message_at": "2026-04-03T03:14:15.000Z",
      "last_message_preview": "Can I check in early?",
      "created_at": "2026-04-01T17:22:10.000Z",
      "updated_at": "2026-04-03T03:14:15.000Z"
    }
  ],
  "next_cursor": "page-token",
  "has_more": true
}