List contacts
Lists everyone who has messaged the workspace, one row per contact, newest activity first. Mirrors the console’s Contacts page: the same search, country, channel, assignment, and open-conversation filters, plus facet counts for building filter UIs.
Contacts are created automatically when a customer first messages the workspace — they cannot be created or deleted through the API.
Authorizations
Workspace API token created in Settings → API. Tokens start with adraa_.
Query Parameters
Matches against the contact's name, email, and phone.
160"sara"
ISO-3166 alpha-2 country code, derived from the contact's phone number. Use the facets.countries of an unfiltered request to see which codes are present.
2"SA"
Only contacts who have a conversation on this channel.
web, whatsapp, facebook, telegram, sms, email assigned — the contact's latest conversation has an agent; unassigned — it does not.
assigned, unassigned When true, only contacts with at least one open conversation.
1-based page number. Clamped to the last page when out of range.
x >= 1Contacts per page.
1 <= x <= 100activity (default) is the page-based, last-activity order. created switches to a lightweight, cursor-paginated, newest-first listing by the contact's first appearance in the workspace — for polling new contacts.
activity, created Used only with sort=created: the nextCursor from the previous page.
Used only with sort=created: page size (1–100).
1 <= x <= 100Response
One page of contacts plus facet counts