Skip to main content
POST
Search contacts with filter body

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
page
integer | null

Page number, starting at 1.

Required range: 1 <= x <= 9007199254740991
perPage
integer | null

Number of items per page.

Required range: 1 <= x <= 9007199254740991
sort
object[] | null

Sort order as [{ id, desc }] column/direction pairs.

keyword
string

Case-insensitive substring match against the contact's name, email, or phone.

contactFilter
object

Structured filter for advanced matching beyond keyword. See contacts.listFilterFields for the field/operator reference.

channels
enum<string>[]

Restrict to contacts with at least one inbox on one of these channels.

Available options:
omnichannel,
webchat,
messenger,
whatsapp,
zalo,
smtp,
telegram,
instagram,
threads,
tiktok,
api
integrationWhatsappId
string

Restrict to contacts reachable via this WhatsApp integration id.

Pattern: ^\d+$
integrationMessengerId
string

Restrict to contacts reachable via this Messenger integration id.

Pattern: ^\d+$
inboxIds
string[]

Restrict to contacts with at least one conversation in one of these inbox ids.

Pattern: ^\d+$
subaction
enum<string>

Broadcast recipient sub-action filter.

Available options:
allContacts,
messengerActiveContacts,
messengerTemplateMessage,
whatsappTemplateMessage,
whatsappWithin24Hours,
instagramActiveContacts,
telegramAllContacts,
tiktokActiveContacts
include
enum<string>[]

Relations to embed in each contact. Omit to include everything (default); pass an empty selection or a narrower list — e.g. ["tags"] — to shrink the response when scanning many contacts.

Available options:
tags,
customFields,
inboxes,
conversation
withCount
boolean
default:true

Whether to compute totalCount/pageCount. Set to false to skip the count query when you only need the rows — faster on large workspaces.

Response

OK

data
object[]
required
pageCount
number
required
totalCount
number
required
totalCountCapped
boolean
required