curl --request GET \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts/search \
--header 'Authorization: Bearer <token>' \
--header 'cloudchat-instance: <cloudchat-instance>'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts/search"
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'cloudchat-instance': '<cloudchat-instance>', Authorization: 'Bearer <token>'}
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/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://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"cloudchat-instance: <cloudchat-instance>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts/search"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("cloudchat-instance", "<cloudchat-instance>")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts/search")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": 815,
"name": "Jane Doe",
"email": "jane@example.com",
"phone_number": "+5511999998888",
"identifier": "crm-42",
"custom_attributes": {
"plan": "pro"
},
"created_at": "2026-09-02T14:03:11.215Z",
"last_activity_at": "2026-10-20T09:41:27.000Z"
}
],
"meta": {
"per_page": 20,
"has_next": false
}
}{
"error": {
"code": "bad_request",
"message": "The request is malformed."
}
}{
"error": {
"code": "unauthorized",
"message": "Authentication is required. Send a valid Bearer token in the Authorization header."
}
}{
"error": {
"code": "forbidden",
"message": "Contact data is available to account administrators only. Ask an administrator of this account to run this request."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found.",
"details": [
{
"field": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}Search contacts
Finds contacts from free text — a name, an email address, a phone number or an identifier — and returns them with their ids, which the other contact and conversation endpoints take. Use it when you know who the person is but not the contact id; to walk the whole base use list contacts.
The text is matched anywhere inside each field, ignoring case, and also inside the company name stored on the contact. A phone number can be typed in any common format (11 98765-4321, +55 11 98765-4321, or only its last digits), and a Brazilian number matches with or without the ninth digit. The text needs at least 3 characters.
A search never returns more than 20 contacts, in no particular order, and it has no total and no next page. When meta.has_next is true, more contacts match than the response holds: make the text more specific instead of asking for more. Contacts that carry no email, phone number, identifier or WhatsApp username are not returned.
Only account administrators can search contacts through this API.
curl --request GET \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts/search \
--header 'Authorization: Bearer <token>' \
--header 'cloudchat-instance: <cloudchat-instance>'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts/search"
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'cloudchat-instance': '<cloudchat-instance>', Authorization: 'Bearer <token>'}
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/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://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"cloudchat-instance: <cloudchat-instance>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts/search"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("cloudchat-instance", "<cloudchat-instance>")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts/search")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": 815,
"name": "Jane Doe",
"email": "jane@example.com",
"phone_number": "+5511999998888",
"identifier": "crm-42",
"custom_attributes": {
"plan": "pro"
},
"created_at": "2026-09-02T14:03:11.215Z",
"last_activity_at": "2026-10-20T09:41:27.000Z"
}
],
"meta": {
"per_page": 20,
"has_next": false
}
}{
"error": {
"code": "bad_request",
"message": "The request is malformed."
}
}{
"error": {
"code": "unauthorized",
"message": "Authentication is required. Send a valid Bearer token in the Authorization header."
}
}{
"error": {
"code": "forbidden",
"message": "Contact data is available to account administrators only. Ask an administrator of this account to run this request."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found.",
"details": [
{
"field": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}Authorizations
Headers
Your Cloud Chat instance ID — an integer, fixed for your company, told at onboarding. The API overview explains how instances work, how to find yours, and the errors a wrong or missing value produces.
1
Path Parameters
Your Cloud Chat account. It has to be an account your token grants membership on, and it has to live on the instance in the cloudchat-instance header — the two travel together. Account numbers are only unique within an instance, so the same number is a different company on another instance. Usually a mismatched pair fails closed with a 401, because your user does not exist on the other instance — but if your identity happens to exist on both, the call succeeds against the other company's data, silently. Read it and you are looking at the wrong help center; write it and you have stored into the wrong account. Send the two values that were given to you together, and never try a number to see what answers.
1
Query Parameters
The text to look for: a name, an email address, a phone number or an identifier. From 3 to 200 characters; a leading + and extra spaces are ignored, and % and _ are matched literally. Missing, shorter than 3 characters, longer than 200, or sent as an array (search[]=) answers 400, with error.details naming search.
"maria.silva@example.com"
Response
The contacts that match, with meta.has_next telling whether more match than data holds.