Search contacts with filter body
Use this when a large or nested contactFilter cannot fit conveniently in query parameters. It returns the same contact data as contacts.list, including include and withCount options.
curl --request POST \
--url https://app.chatbotx.io/api/v1/contacts/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"page": 4503599627370496,
"perPage": 4503599627370496,
"sort": [
{
"id": "<string>",
"desc": true
}
],
"keyword": "<string>",
"channels": [],
"integrationWhatsappId": "<string>",
"integrationMessengerId": "<string>",
"inboxIds": [
"<string>"
],
"include": [],
"withCount": true
}
'import requests
url = "https://app.chatbotx.io/api/v1/contacts/search"
payload = {
"page": 4503599627370496,
"perPage": 4503599627370496,
"sort": [
{
"id": "<string>",
"desc": True
}
],
"keyword": "<string>",
"channels": [],
"integrationWhatsappId": "<string>",
"integrationMessengerId": "<string>",
"inboxIds": ["<string>"],
"include": [],
"withCount": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
page: 4503599627370496,
perPage: 4503599627370496,
sort: [{id: '<string>', desc: true}],
keyword: '<string>',
channels: [],
integrationWhatsappId: '<string>',
integrationMessengerId: '<string>',
inboxIds: ['<string>'],
include: [],
withCount: true
})
};
fetch('https://app.chatbotx.io/api/v1/contacts/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.chatbotx.io/api/v1/contacts/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'page' => 4503599627370496,
'perPage' => 4503599627370496,
'sort' => [
[
'id' => '<string>',
'desc' => true
]
],
'keyword' => '<string>',
'channels' => [
],
'integrationWhatsappId' => '<string>',
'integrationMessengerId' => '<string>',
'inboxIds' => [
'<string>'
],
'include' => [
],
'withCount' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.chatbotx.io/api/v1/contacts/search"
payload := strings.NewReader("{\n \"page\": 4503599627370496,\n \"perPage\": 4503599627370496,\n \"sort\": [\n {\n \"id\": \"<string>\",\n \"desc\": true\n }\n ],\n \"keyword\": \"<string>\",\n \"channels\": [],\n \"integrationWhatsappId\": \"<string>\",\n \"integrationMessengerId\": \"<string>\",\n \"inboxIds\": [\n \"<string>\"\n ],\n \"include\": [],\n \"withCount\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.chatbotx.io/api/v1/contacts/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"page\": 4503599627370496,\n \"perPage\": 4503599627370496,\n \"sort\": [\n {\n \"id\": \"<string>\",\n \"desc\": true\n }\n ],\n \"keyword\": \"<string>\",\n \"channels\": [],\n \"integrationWhatsappId\": \"<string>\",\n \"integrationMessengerId\": \"<string>\",\n \"inboxIds\": [\n \"<string>\"\n ],\n \"include\": [],\n \"withCount\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.chatbotx.io/api/v1/contacts/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"page\": 4503599627370496,\n \"perPage\": 4503599627370496,\n \"sort\": [\n {\n \"id\": \"<string>\",\n \"desc\": true\n }\n ],\n \"keyword\": \"<string>\",\n \"channels\": [],\n \"integrationWhatsappId\": \"<string>\",\n \"integrationMessengerId\": \"<string>\",\n \"inboxIds\": [\n \"<string>\"\n ],\n \"include\": [],\n \"withCount\": true\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"avatar": "<string>",
"phoneNumber": "<string>",
"email": "<string>",
"emailVerified": true,
"emailOptIn": true,
"firstName": "<string>",
"lastName": "<string>",
"fullName": "<string>",
"gender": "male",
"lastReadAt": "2023-11-07T05:31:56Z",
"ref": "<string>",
"country": "<string>",
"state": "<string>",
"city": "<string>",
"location": "<string>",
"locale": "<string>",
"timezone": "<string>",
"subscribedAt": "2023-11-07T05:31:56Z",
"broadcastSubscribedAt": "2023-11-07T05:31:56Z",
"blockedAt": "2023-11-07T05:31:56Z",
"workspaceId": "<string>",
"contactCustomFields": [
{
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"value": "<string>",
"contactId": "<string>",
"customFieldId": "<string>"
}
],
"tags": [
{
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"name": "<string>",
"deletedAt": "2023-11-07T05:31:56Z",
"folderId": "<string>",
"workspaceId": "<string>"
}
],
"contactNotes": [
{
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"text": "<string>",
"contactId": "<string>",
"createdById": "<string>"
}
],
"contactInboxes": [
{
"id": "<string>",
"contactId": "<string>",
"inboxId": "<string>",
"channel": "<string>",
"source": "<string>",
"sourceId": "<string>",
"language": "<string>",
"lastIncomingMessageAt": "2023-11-07T05:31:56Z",
"inbox": {
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"name": "<string>",
"channel": "<string>",
"sourceId": "<string>",
"workspaceId": "<string>",
"status": "<string>",
"disconnectedAt": "2023-11-07T05:31:56Z",
"disconnectReason": "<string>"
},
"sourceUserId": "<string>",
"sourceUsername": "<string>",
"contactLastReadAt": "2023-11-07T05:31:56Z"
}
],
"conversation": {
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"botEnabled": true,
"botResumeAt": "2023-11-07T05:31:56Z",
"archivedAt": "2023-11-07T05:31:56Z",
"additionalAttributes": "<string>",
"contactLastReadAt": "2023-11-07T05:31:56Z",
"agentLastReadAt": "2023-11-07T05:31:56Z",
"lastActivityAt": "2023-11-07T05:31:56Z",
"followed": true,
"workspaceId": "<string>",
"contactId": "<string>",
"sourceId": "<string>",
"lastStep": "<string>",
"currentStep": "<string>",
"adminRepliedAt": "2023-11-07T05:31:56Z",
"contactRepliedAt": "2023-11-07T05:31:56Z",
"aiContextLastMessageId": null,
"assignedUserId": null,
"assignedInboxTeamId": null,
"assignedUser": {
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"name": "<string>",
"email": "<string>",
"emailVerified": true,
"image": "<string>",
"isAnonymous": true,
"mustChangePassword": true,
"tenantId": "<unknown>"
},
"assignedInboxTeam": {
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"workspaceId": "<string>",
"name": "<string>"
},
"inbox": {
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"name": "<string>",
"channel": "<string>",
"sourceId": "<string>",
"workspaceId": "<string>",
"status": "<string>",
"disconnectedAt": "2023-11-07T05:31:56Z",
"disconnectReason": "<string>"
}
}
}
],
"pageCount": 123,
"totalCount": 123,
"totalCountCapped": true
}{
"defined": true,
"code": "businessError",
"status": 400,
"message": "An error occurred while processing your request",
"data": "<unknown>"
}{
"defined": true,
"code": "UNAUTHORIZED",
"status": 401,
"message": "Authentication required",
"data": "<unknown>"
}{
"defined": true,
"code": "FORBIDDEN",
"status": 403,
"message": "You do not have permission to perform this action",
"data": "<unknown>"
}{
"defined": true,
"code": "invalidRequestData",
"status": 422,
"message": "Input validation failed",
"data": {
"issues": [
{
"message": "<string>",
"path": [
"<string>"
]
}
]
}
}{
"defined": true,
"code": "tooManyRequests",
"status": 429,
"message": "Too many requests",
"data": "<unknown>"
}{
"defined": true,
"code": "INTERNAL_SERVER_ERROR",
"status": 500,
"message": "An unexpected error occurred",
"data": "<unknown>"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Page number, starting at 1.
1 <= x <= 9007199254740991Number of items per page.
1 <= x <= 9007199254740991Sort order as [{ id, desc }] column/direction pairs.
Show child attributes
Show child attributes
Case-insensitive substring match against the contact's name, email, or phone.
Structured filter for advanced matching beyond keyword. See contacts.listFilterFields for the field/operator reference.
Show child attributes
Show child attributes
Restrict to contacts with at least one inbox on one of these channels.
omnichannel, webchat, messenger, whatsapp, zalo, smtp, telegram, instagram, threads, tiktok, api Restrict to contacts reachable via this WhatsApp integration id.
^\d+$Restrict to contacts reachable via this Messenger integration id.
^\d+$Restrict to contacts with at least one conversation in one of these inbox ids.
^\d+$Broadcast recipient sub-action filter.
allContacts, messengerActiveContacts, messengerTemplateMessage, whatsappTemplateMessage, whatsappWithin24Hours, instagramActiveContacts, telegramAllContacts, tiktokActiveContacts 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.
tags, customFields, inboxes, conversation Whether to compute totalCount/pageCount. Set to false to skip the count query when you only need the rows — faster on large workspaces.
Was this page helpful?
curl --request POST \
--url https://app.chatbotx.io/api/v1/contacts/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"page": 4503599627370496,
"perPage": 4503599627370496,
"sort": [
{
"id": "<string>",
"desc": true
}
],
"keyword": "<string>",
"channels": [],
"integrationWhatsappId": "<string>",
"integrationMessengerId": "<string>",
"inboxIds": [
"<string>"
],
"include": [],
"withCount": true
}
'import requests
url = "https://app.chatbotx.io/api/v1/contacts/search"
payload = {
"page": 4503599627370496,
"perPage": 4503599627370496,
"sort": [
{
"id": "<string>",
"desc": True
}
],
"keyword": "<string>",
"channels": [],
"integrationWhatsappId": "<string>",
"integrationMessengerId": "<string>",
"inboxIds": ["<string>"],
"include": [],
"withCount": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
page: 4503599627370496,
perPage: 4503599627370496,
sort: [{id: '<string>', desc: true}],
keyword: '<string>',
channels: [],
integrationWhatsappId: '<string>',
integrationMessengerId: '<string>',
inboxIds: ['<string>'],
include: [],
withCount: true
})
};
fetch('https://app.chatbotx.io/api/v1/contacts/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.chatbotx.io/api/v1/contacts/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'page' => 4503599627370496,
'perPage' => 4503599627370496,
'sort' => [
[
'id' => '<string>',
'desc' => true
]
],
'keyword' => '<string>',
'channels' => [
],
'integrationWhatsappId' => '<string>',
'integrationMessengerId' => '<string>',
'inboxIds' => [
'<string>'
],
'include' => [
],
'withCount' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.chatbotx.io/api/v1/contacts/search"
payload := strings.NewReader("{\n \"page\": 4503599627370496,\n \"perPage\": 4503599627370496,\n \"sort\": [\n {\n \"id\": \"<string>\",\n \"desc\": true\n }\n ],\n \"keyword\": \"<string>\",\n \"channels\": [],\n \"integrationWhatsappId\": \"<string>\",\n \"integrationMessengerId\": \"<string>\",\n \"inboxIds\": [\n \"<string>\"\n ],\n \"include\": [],\n \"withCount\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.chatbotx.io/api/v1/contacts/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"page\": 4503599627370496,\n \"perPage\": 4503599627370496,\n \"sort\": [\n {\n \"id\": \"<string>\",\n \"desc\": true\n }\n ],\n \"keyword\": \"<string>\",\n \"channels\": [],\n \"integrationWhatsappId\": \"<string>\",\n \"integrationMessengerId\": \"<string>\",\n \"inboxIds\": [\n \"<string>\"\n ],\n \"include\": [],\n \"withCount\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.chatbotx.io/api/v1/contacts/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"page\": 4503599627370496,\n \"perPage\": 4503599627370496,\n \"sort\": [\n {\n \"id\": \"<string>\",\n \"desc\": true\n }\n ],\n \"keyword\": \"<string>\",\n \"channels\": [],\n \"integrationWhatsappId\": \"<string>\",\n \"integrationMessengerId\": \"<string>\",\n \"inboxIds\": [\n \"<string>\"\n ],\n \"include\": [],\n \"withCount\": true\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"avatar": "<string>",
"phoneNumber": "<string>",
"email": "<string>",
"emailVerified": true,
"emailOptIn": true,
"firstName": "<string>",
"lastName": "<string>",
"fullName": "<string>",
"gender": "male",
"lastReadAt": "2023-11-07T05:31:56Z",
"ref": "<string>",
"country": "<string>",
"state": "<string>",
"city": "<string>",
"location": "<string>",
"locale": "<string>",
"timezone": "<string>",
"subscribedAt": "2023-11-07T05:31:56Z",
"broadcastSubscribedAt": "2023-11-07T05:31:56Z",
"blockedAt": "2023-11-07T05:31:56Z",
"workspaceId": "<string>",
"contactCustomFields": [
{
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"value": "<string>",
"contactId": "<string>",
"customFieldId": "<string>"
}
],
"tags": [
{
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"name": "<string>",
"deletedAt": "2023-11-07T05:31:56Z",
"folderId": "<string>",
"workspaceId": "<string>"
}
],
"contactNotes": [
{
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"text": "<string>",
"contactId": "<string>",
"createdById": "<string>"
}
],
"contactInboxes": [
{
"id": "<string>",
"contactId": "<string>",
"inboxId": "<string>",
"channel": "<string>",
"source": "<string>",
"sourceId": "<string>",
"language": "<string>",
"lastIncomingMessageAt": "2023-11-07T05:31:56Z",
"inbox": {
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"name": "<string>",
"channel": "<string>",
"sourceId": "<string>",
"workspaceId": "<string>",
"status": "<string>",
"disconnectedAt": "2023-11-07T05:31:56Z",
"disconnectReason": "<string>"
},
"sourceUserId": "<string>",
"sourceUsername": "<string>",
"contactLastReadAt": "2023-11-07T05:31:56Z"
}
],
"conversation": {
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"botEnabled": true,
"botResumeAt": "2023-11-07T05:31:56Z",
"archivedAt": "2023-11-07T05:31:56Z",
"additionalAttributes": "<string>",
"contactLastReadAt": "2023-11-07T05:31:56Z",
"agentLastReadAt": "2023-11-07T05:31:56Z",
"lastActivityAt": "2023-11-07T05:31:56Z",
"followed": true,
"workspaceId": "<string>",
"contactId": "<string>",
"sourceId": "<string>",
"lastStep": "<string>",
"currentStep": "<string>",
"adminRepliedAt": "2023-11-07T05:31:56Z",
"contactRepliedAt": "2023-11-07T05:31:56Z",
"aiContextLastMessageId": null,
"assignedUserId": null,
"assignedInboxTeamId": null,
"assignedUser": {
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"name": "<string>",
"email": "<string>",
"emailVerified": true,
"image": "<string>",
"isAnonymous": true,
"mustChangePassword": true,
"tenantId": "<unknown>"
},
"assignedInboxTeam": {
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"workspaceId": "<string>",
"name": "<string>"
},
"inbox": {
"id": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"name": "<string>",
"channel": "<string>",
"sourceId": "<string>",
"workspaceId": "<string>",
"status": "<string>",
"disconnectedAt": "2023-11-07T05:31:56Z",
"disconnectReason": "<string>"
}
}
}
],
"pageCount": 123,
"totalCount": 123,
"totalCountCapped": true
}{
"defined": true,
"code": "businessError",
"status": 400,
"message": "An error occurred while processing your request",
"data": "<unknown>"
}{
"defined": true,
"code": "UNAUTHORIZED",
"status": 401,
"message": "Authentication required",
"data": "<unknown>"
}{
"defined": true,
"code": "FORBIDDEN",
"status": 403,
"message": "You do not have permission to perform this action",
"data": "<unknown>"
}{
"defined": true,
"code": "invalidRequestData",
"status": 422,
"message": "Input validation failed",
"data": {
"issues": [
{
"message": "<string>",
"path": [
"<string>"
]
}
]
}
}{
"defined": true,
"code": "tooManyRequests",
"status": 429,
"message": "Too many requests",
"data": "<unknown>"
}{
"defined": true,
"code": "INTERNAL_SERVER_ERROR",
"status": 500,
"message": "An unexpected error occurred",
"data": "<unknown>"
}