curl --request GET \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/companies \
--header 'Authorization: Bearer <token>' \
--header 'cloudchat-instance: <cloudchat-instance>'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/companies"
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}/companies', 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}/companies",
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}/companies"
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}/companies")
.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}/companies")
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": 314,
"name": "Transportadora Rápida",
"domain": "rapida.com.br",
"description": "Transportadora parceira para entregas no Sudeste.",
"contacts_count": 3,
"labels": [
"transportadora"
],
"custom_attributes": {
"cnpj": "12345678000190",
"rm_responsavel": "Ana Lima",
"operacoes": [
"Last mile",
"Reversa"
]
},
"created_at": "2026-08-14T12:30:05.412Z",
"updated_at": "2026-10-28T17:02:41.903Z"
}
],
"meta": {
"current_page": 1,
"per_page": 25,
"has_next": false
}
}{
"error": {
"code": "bad_request",
"message": "The request is malformed.",
"details": [
{
"field": "attribute_key",
"code": "invalid",
"message": "This is not a company custom attribute you can read. Available attributes: cnpj, operacoes, rm_responsavel."
}
]
}
}{
"error": {
"code": "unauthorized",
"message": "Authentication is required. Send a valid Bearer token in the Authorization header."
}
}{
"error": {
"code": "forbidden",
"message": "Companies are not enabled for this account."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"message": "API rate limit exceeded"
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}List companies
Returns the companies of the account, ordered by name, one page at a time.
Find a company by one of its attributes. Send attribute_key and attribute_value together for an exact match on one company custom attribute — for example attribute_key=cnpj&attribute_value=12345678000190. This is the reliable way to resolve a company from an identifier your own systems hold. The key has to be a company attribute your role can read; anything else answers 400, and the message lists the keys you can use.
Search. search matches the company name, the domain, or the value of an attribute you can see. Use it to explore; use the attribute filter when you need one exact company. search does not normalize punctuation, so to find a company by CNPJ use attribute_key and attribute_value, not search.
The two can be combined. Walk the pages while meta.has_next is true.
curl --request GET \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/companies \
--header 'Authorization: Bearer <token>' \
--header 'cloudchat-instance: <cloudchat-instance>'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/companies"
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}/companies', 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}/companies",
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}/companies"
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}/companies")
.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}/companies")
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": 314,
"name": "Transportadora Rápida",
"domain": "rapida.com.br",
"description": "Transportadora parceira para entregas no Sudeste.",
"contacts_count": 3,
"labels": [
"transportadora"
],
"custom_attributes": {
"cnpj": "12345678000190",
"rm_responsavel": "Ana Lima",
"operacoes": [
"Last mile",
"Reversa"
]
},
"created_at": "2026-08-14T12:30:05.412Z",
"updated_at": "2026-10-28T17:02:41.903Z"
}
],
"meta": {
"current_page": 1,
"per_page": 25,
"has_next": false
}
}{
"error": {
"code": "bad_request",
"message": "The request is malformed.",
"details": [
{
"field": "attribute_key",
"code": "invalid",
"message": "This is not a company custom attribute you can read. Available attributes: cnpj, operacoes, rm_responsavel."
}
]
}
}{
"error": {
"code": "unauthorized",
"message": "Authentication is required. Send a valid Bearer token in the Authorization header."
}
}{
"error": {
"code": "forbidden",
"message": "Companies are not enabled for this account."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"message": "API rate limit exceeded"
}{
"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
Text matched against the company name, the domain and the values of the company attributes your role can see. Punctuation is not normalized: 12.345.678/0001-90 does not find a company stored as 12345678000190. For a CNPJ or another identifier, filter with attribute_key and attribute_value instead. Longer than 200 characters, it is cut to the first 200. Sent as an array or an object (search[]=), it answers 400.
200"rapida"
The key of a company custom attribute, for an exact match together with attribute_value. Sending only one of the two, or a key that is not a company attribute your role can read, answers 400 with error.details naming attribute_key; the message lists the keys available to you.
"cnpj"
The value attribute_key must hold, compared as text and exactly — no partial match, no case folding, and spaces count: the value is compared as you send it.
One exception, for document numbers such as a CNPJ, and only on a text attribute: when the value you send has at least 8 digits and contains only digits, dots, slashes, hyphens or spaces, a stored value made of those same characters, with at least 8 digits, also matches if its digits alone are the same — on this path punctuation and spaces are ignored on both sides. So 12.345.678/0001-90 finds a company stored as 12345678000190, and 12345678000190 finds one stored as 12.345.678/0001-90. Number and date attributes never match by digits — send them exactly as stored.
"12345678000190"