curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-views \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"custom_view": {
"name": "Open and unassigned",
"filter_type": "conversation",
"query": {
"payload": [
{
"attribute_key": "status",
"filter_operator": "equal_to",
"values": [
"open"
],
"query_operator": "and"
},
{
"attribute_key": "assignee_id",
"filter_operator": "is_not_present"
}
]
},
"visibility": "private",
"team_ids": []
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-views"
payload = { "custom_view": {
"name": "Open and unassigned",
"filter_type": "conversation",
"query": { "payload": [
{
"attribute_key": "status",
"filter_operator": "equal_to",
"values": ["open"],
"query_operator": "and"
},
{
"attribute_key": "assignee_id",
"filter_operator": "is_not_present"
}
] },
"visibility": "private",
"team_ids": []
} }
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'cloudchat-instance': '<cloudchat-instance>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
custom_view: {
name: 'Open and unassigned',
filter_type: 'conversation',
query: {
payload: [
{
attribute_key: 'status',
filter_operator: 'equal_to',
values: ['open'],
query_operator: 'and'
},
{attribute_key: 'assignee_id', filter_operator: 'is_not_present'}
]
},
visibility: 'private',
team_ids: []
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-views', 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}/custom-views",
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([
'custom_view' => [
'name' => 'Open and unassigned',
'filter_type' => 'conversation',
'query' => [
'payload' => [
[
'attribute_key' => 'status',
'filter_operator' => 'equal_to',
'values' => [
'open'
],
'query_operator' => 'and'
],
[
'attribute_key' => 'assignee_id',
'filter_operator' => 'is_not_present'
]
]
],
'visibility' => 'private',
'team_ids' => [
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-views"
payload := strings.NewReader("{\n \"custom_view\": {\n \"name\": \"Open and unassigned\",\n \"filter_type\": \"conversation\",\n \"query\": {\n \"payload\": [\n {\n \"attribute_key\": \"status\",\n \"filter_operator\": \"equal_to\",\n \"values\": [\n \"open\"\n ],\n \"query_operator\": \"and\"\n },\n {\n \"attribute_key\": \"assignee_id\",\n \"filter_operator\": \"is_not_present\"\n }\n ]\n },\n \"visibility\": \"private\",\n \"team_ids\": []\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("cloudchat-instance", "<cloudchat-instance>")
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://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-views")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"custom_view\": {\n \"name\": \"Open and unassigned\",\n \"filter_type\": \"conversation\",\n \"query\": {\n \"payload\": [\n {\n \"attribute_key\": \"status\",\n \"filter_operator\": \"equal_to\",\n \"values\": [\n \"open\"\n ],\n \"query_operator\": \"and\"\n },\n {\n \"attribute_key\": \"assignee_id\",\n \"filter_operator\": \"is_not_present\"\n }\n ]\n },\n \"visibility\": \"private\",\n \"team_ids\": []\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-views")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"custom_view\": {\n \"name\": \"Open and unassigned\",\n \"filter_type\": \"conversation\",\n \"query\": {\n \"payload\": [\n {\n \"attribute_key\": \"status\",\n \"filter_operator\": \"equal_to\",\n \"values\": [\n \"open\"\n ],\n \"query_operator\": \"and\"\n },\n {\n \"attribute_key\": \"assignee_id\",\n \"filter_operator\": \"is_not_present\"\n }\n ]\n },\n \"visibility\": \"private\",\n \"team_ids\": []\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 14,
"name": "Open and unassigned",
"filter_type": "conversation",
"visibility": "private",
"team_ids": [],
"query": {
"payload": [
{
"attribute_key": "status",
"filter_operator": "equal_to",
"values": [
"open"
],
"query_operator": "and"
},
{
"attribute_key": "assignee_id",
"filter_operator": "is_not_present"
}
]
},
"owned_by_me": true,
"created_at": "2026-11-02T11:04:17.000Z",
"updated_at": "2026-11-05T14:32:05.123Z"
}{
"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": "This account is suspended."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "query",
"code": "invalid",
"message": "payload[0]: the operator contains is not available for the number attribute age. Use one of: equal_to, not_equal_to, is_present, is_not_present, is_greater_than, is_less_than."
}
]
}
}{
"message": "API rate limit exceeded"
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}Create a custom view
Creates a custom view owned by the caller. The owner always comes from the token: nothing in the body can name another owner or account. Every role can create views. The body goes under a custom_view wrapper.
name, filter_type and query are required. filter_type is conversation or contact and cannot be changed afterwards.
visibility is private when left out. public shares the view with everyone in the account, and team shares it with the members of the teams in team_ids, which must belong to the account. team exists for conversation views only, as in the dashboard. A shared view shows up in the sidebar of its audience right away.
The filter is the query: an object with a payload list of conditions, each with attribute_key, filter_operator, values and query_operator. attribute_key is a filter attribute of the view type, or a custom attribute of the account for that type (conversation attributes for a conversation view, contact attributes for a contact view). filter_operator has to be one the attribute supports. values is a list of values that may be empty only with is_present and is_not_present, and each value has to fit the attribute: text for text, list, link and multi-list attributes and for most standard ones, whole numbers for assignee_id, inbox_id, team_id, display_id, campaign_id and csat_rating, numbers for number custom attributes, true or false for checkbox attributes, proactively_initiated and blocked, dates as YYYY-MM-DD for date attributes and for is_greater_than and is_less_than on created_at, last_activity_at and resolved_at, and a whole number of days for days_before. A value of the wrong type is refused with a 422, because the view would not open. query_operator is and or or (any case is accepted; it is stored and returned in lowercase, the way the dashboard writes it), joins a condition to the next one, and is required on every condition except the last, which must not carry one. A condition with any other key, an unknown attribute, or an operator the attribute does not support is refused with a 422 that names the condition and lists what is accepted.
Each person can have a limited number of views per account; past it the call is refused with a 422.
curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-views \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"custom_view": {
"name": "Open and unassigned",
"filter_type": "conversation",
"query": {
"payload": [
{
"attribute_key": "status",
"filter_operator": "equal_to",
"values": [
"open"
],
"query_operator": "and"
},
{
"attribute_key": "assignee_id",
"filter_operator": "is_not_present"
}
]
},
"visibility": "private",
"team_ids": []
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-views"
payload = { "custom_view": {
"name": "Open and unassigned",
"filter_type": "conversation",
"query": { "payload": [
{
"attribute_key": "status",
"filter_operator": "equal_to",
"values": ["open"],
"query_operator": "and"
},
{
"attribute_key": "assignee_id",
"filter_operator": "is_not_present"
}
] },
"visibility": "private",
"team_ids": []
} }
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'cloudchat-instance': '<cloudchat-instance>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
custom_view: {
name: 'Open and unassigned',
filter_type: 'conversation',
query: {
payload: [
{
attribute_key: 'status',
filter_operator: 'equal_to',
values: ['open'],
query_operator: 'and'
},
{attribute_key: 'assignee_id', filter_operator: 'is_not_present'}
]
},
visibility: 'private',
team_ids: []
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-views', 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}/custom-views",
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([
'custom_view' => [
'name' => 'Open and unassigned',
'filter_type' => 'conversation',
'query' => [
'payload' => [
[
'attribute_key' => 'status',
'filter_operator' => 'equal_to',
'values' => [
'open'
],
'query_operator' => 'and'
],
[
'attribute_key' => 'assignee_id',
'filter_operator' => 'is_not_present'
]
]
],
'visibility' => 'private',
'team_ids' => [
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-views"
payload := strings.NewReader("{\n \"custom_view\": {\n \"name\": \"Open and unassigned\",\n \"filter_type\": \"conversation\",\n \"query\": {\n \"payload\": [\n {\n \"attribute_key\": \"status\",\n \"filter_operator\": \"equal_to\",\n \"values\": [\n \"open\"\n ],\n \"query_operator\": \"and\"\n },\n {\n \"attribute_key\": \"assignee_id\",\n \"filter_operator\": \"is_not_present\"\n }\n ]\n },\n \"visibility\": \"private\",\n \"team_ids\": []\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("cloudchat-instance", "<cloudchat-instance>")
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://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-views")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"custom_view\": {\n \"name\": \"Open and unassigned\",\n \"filter_type\": \"conversation\",\n \"query\": {\n \"payload\": [\n {\n \"attribute_key\": \"status\",\n \"filter_operator\": \"equal_to\",\n \"values\": [\n \"open\"\n ],\n \"query_operator\": \"and\"\n },\n {\n \"attribute_key\": \"assignee_id\",\n \"filter_operator\": \"is_not_present\"\n }\n ]\n },\n \"visibility\": \"private\",\n \"team_ids\": []\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-views")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"custom_view\": {\n \"name\": \"Open and unassigned\",\n \"filter_type\": \"conversation\",\n \"query\": {\n \"payload\": [\n {\n \"attribute_key\": \"status\",\n \"filter_operator\": \"equal_to\",\n \"values\": [\n \"open\"\n ],\n \"query_operator\": \"and\"\n },\n {\n \"attribute_key\": \"assignee_id\",\n \"filter_operator\": \"is_not_present\"\n }\n ]\n },\n \"visibility\": \"private\",\n \"team_ids\": []\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 14,
"name": "Open and unassigned",
"filter_type": "conversation",
"visibility": "private",
"team_ids": [],
"query": {
"payload": [
{
"attribute_key": "status",
"filter_operator": "equal_to",
"values": [
"open"
],
"query_operator": "and"
},
{
"attribute_key": "assignee_id",
"filter_operator": "is_not_present"
}
]
},
"owned_by_me": true,
"created_at": "2026-11-02T11:04:17.000Z",
"updated_at": "2026-11-05T14:32:05.123Z"
}{
"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": "This account is suspended."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "query",
"code": "invalid",
"message": "payload[0]: the operator contains is not available for the number attribute age. Use one of: equal_to, not_equal_to, is_present, is_not_present, is_greater_than, is_less_than."
}
]
}
}{
"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
Body
Response
Created. The body is the view itself, not wrapped in data.
A saved filter of conversations or contacts, kept in the dashboard sidebar.
The saved filter. Normally { "payload": [...] } with the conditions described on CustomViewCondition; views saved by older versions of the dashboard may carry other keys, which are returned as stored.
{ "payload": [ { "attribute_key": "status", "filter_operator": "equal_to", "values": ["open"], "query_operator": "and" }, { "attribute_key": "assignee_id", "filter_operator": "is_not_present" } ] }