Skip to main content
GET
List contacts

Authorizations

Authorization
string
header
required

Workspace API token created in Settings → API. Tokens start with adraa_.

Query Parameters

Matches against the contact's name, email, and phone.

Maximum string length: 160
Example:

"sara"

country
string

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.

Required string length: 2
Example:

"SA"

channel
enum<string>

Only contacts who have a conversation on this channel.

Available options:
web,
whatsapp,
facebook,
telegram,
sms,
email
assignment
enum<string>

assigned — the contact's latest conversation has an agent; unassigned — it does not.

Available options:
assigned,
unassigned
hasOpen
boolean

When true, only contacts with at least one open conversation.

page
integer
default:1

1-based page number. Clamped to the last page when out of range.

Required range: x >= 1
pageSize
integer
default:20

Contacts per page.

Required range: 1 <= x <= 100
sort
enum<string>
default:activity

activity (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.

Available options:
activity,
created
cursor
string

Used only with sort=created: the nextCursor from the previous page.

limit
integer
default:50

Used only with sort=created: page size (1–100).

Required range: 1 <= x <= 100

Response

One page of contacts plus facet counts

contacts
object[]
total
integer

Contacts matching the filters, across all pages.

Example:

124

page
integer
Example:

1

pageSize
integer
Example:

20

totalPages
integer
Example:

7

facets
object

Counts across the whole directory (unfiltered), for building filter dropdowns.