curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-attributes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"custom_attribute": {
"name": "Plan",
"key": "plan",
"type": "list",
"model": "contact",
"description": "Plan the customer subscribed to.",
"values": [
"free",
"pro",
"enterprise"
],
"required": false
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-attributes"
payload = { "custom_attribute": {
"name": "Plan",
"key": "plan",
"type": "list",
"model": "contact",
"description": "Plan the customer subscribed to.",
"values": ["free", "pro", "enterprise"],
"required": False
} }
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_attribute: {
name: 'Plan',
key: 'plan',
type: 'list',
model: 'contact',
description: 'Plan the customer subscribed to.',
values: ['free', 'pro', 'enterprise'],
required: false
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-attributes', 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-attributes",
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_attribute' => [
'name' => 'Plan',
'key' => 'plan',
'type' => 'list',
'model' => 'contact',
'description' => 'Plan the customer subscribed to.',
'values' => [
'free',
'pro',
'enterprise'
],
'required' => false
]
]),
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-attributes"
payload := strings.NewReader("{\n \"custom_attribute\": {\n \"name\": \"Plan\",\n \"key\": \"plan\",\n \"type\": \"list\",\n \"model\": \"contact\",\n \"description\": \"Plan the customer subscribed to.\",\n \"values\": [\n \"free\",\n \"pro\",\n \"enterprise\"\n ],\n \"required\": false\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-attributes")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"custom_attribute\": {\n \"name\": \"Plan\",\n \"key\": \"plan\",\n \"type\": \"list\",\n \"model\": \"contact\",\n \"description\": \"Plan the customer subscribed to.\",\n \"values\": [\n \"free\",\n \"pro\",\n \"enterprise\"\n ],\n \"required\": false\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-attributes")
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_attribute\": {\n \"name\": \"Plan\",\n \"key\": \"plan\",\n \"type\": \"list\",\n \"model\": \"contact\",\n \"description\": \"Plan the customer subscribed to.\",\n \"values\": [\n \"free\",\n \"pro\",\n \"enterprise\"\n ],\n \"required\": false\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 42,
"key": "plan",
"name": "Plan",
"description": "Plan the customer subscribed to.",
"type": "list",
"model": "contact",
"values": [
"free",
"pro",
"enterprise"
],
"required": false,
"regex_pattern": "/^[0-9]{11}$/",
"regex_cue": "Only the 11 digits of the CPF.",
"conditional": false,
"created_at": "2026-05-02T11:04:17.000Z",
"updated_at": "2026-05-02T11:04:17.000Z"
}{
"error": {
"code": "not_found",
"message": "Resource could not be found.",
"details": [
{
"field": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}{
"error": {
"code": "unauthorized",
"message": "Authentication is required. Send a valid Bearer token in the Authorization header."
}
}{
"error": {
"code": "forbidden",
"message": "You are not allowed to perform this action."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"error": {
"code": "conflict",
"message": "The request conflicts with the current state of the resource.",
"details": [
{
"field": "key",
"code": "taken",
"message": "An attribute with this key already exists for this model (id 42). Read it with getCustomAttribute or choose another key.",
"existing_attribute_id": 42
}
]
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "key",
"code": "invalid",
"message": "The key must use only lowercase letters, digits and underscores, for example customer_tax_id."
}
]
}
}{
"message": "API rate limit exceeded"
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}Create a custom attribute
Administrator only. Creates one custom attribute definition, so that conversations, contacts or companies can start carrying a value for it. The definition goes under custom_attribute.
This operation only creates. The name, description, list options, required and regex can be edited afterwards with updateCustomAttribute, but the key, the type and the model never change, and nothing in this API deletes a definition — an administrator does that in the Cloud Chat screen — so check those three before sending. A list has to be created with its options.
Not accepted here: AI field filling (ai_field_filling_enable, ai_fill_instruction, ai_fill_confidence_threshold), conditional sub-lists and visibility rules. The regex validation is added afterwards with updateCustomAttribute. They are set up in the Cloud Chat screen, and sending any field outside the request schema answers 400 with the field named in details.
The key is unique within its model. A key already used in the same model answers 409 and, when you can read that definition, details[0].existing_attribute_id is its id; the same key in another model is allowed. Creating a definition gives no contact, conversation or company a value for it.
curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-attributes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"custom_attribute": {
"name": "Plan",
"key": "plan",
"type": "list",
"model": "contact",
"description": "Plan the customer subscribed to.",
"values": [
"free",
"pro",
"enterprise"
],
"required": false
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-attributes"
payload = { "custom_attribute": {
"name": "Plan",
"key": "plan",
"type": "list",
"model": "contact",
"description": "Plan the customer subscribed to.",
"values": ["free", "pro", "enterprise"],
"required": False
} }
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_attribute: {
name: 'Plan',
key: 'plan',
type: 'list',
model: 'contact',
description: 'Plan the customer subscribed to.',
values: ['free', 'pro', 'enterprise'],
required: false
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-attributes', 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-attributes",
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_attribute' => [
'name' => 'Plan',
'key' => 'plan',
'type' => 'list',
'model' => 'contact',
'description' => 'Plan the customer subscribed to.',
'values' => [
'free',
'pro',
'enterprise'
],
'required' => false
]
]),
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-attributes"
payload := strings.NewReader("{\n \"custom_attribute\": {\n \"name\": \"Plan\",\n \"key\": \"plan\",\n \"type\": \"list\",\n \"model\": \"contact\",\n \"description\": \"Plan the customer subscribed to.\",\n \"values\": [\n \"free\",\n \"pro\",\n \"enterprise\"\n ],\n \"required\": false\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-attributes")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"custom_attribute\": {\n \"name\": \"Plan\",\n \"key\": \"plan\",\n \"type\": \"list\",\n \"model\": \"contact\",\n \"description\": \"Plan the customer subscribed to.\",\n \"values\": [\n \"free\",\n \"pro\",\n \"enterprise\"\n ],\n \"required\": false\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-attributes")
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_attribute\": {\n \"name\": \"Plan\",\n \"key\": \"plan\",\n \"type\": \"list\",\n \"model\": \"contact\",\n \"description\": \"Plan the customer subscribed to.\",\n \"values\": [\n \"free\",\n \"pro\",\n \"enterprise\"\n ],\n \"required\": false\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 42,
"key": "plan",
"name": "Plan",
"description": "Plan the customer subscribed to.",
"type": "list",
"model": "contact",
"values": [
"free",
"pro",
"enterprise"
],
"required": false,
"regex_pattern": "/^[0-9]{11}$/",
"regex_cue": "Only the 11 digits of the CPF.",
"conditional": false,
"created_at": "2026-05-02T11:04:17.000Z",
"updated_at": "2026-05-02T11:04:17.000Z"
}{
"error": {
"code": "not_found",
"message": "Resource could not be found.",
"details": [
{
"field": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}{
"error": {
"code": "unauthorized",
"message": "Authentication is required. Send a valid Bearer token in the Authorization header."
}
}{
"error": {
"code": "forbidden",
"message": "You are not allowed to perform this action."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"error": {
"code": "conflict",
"message": "The request conflicts with the current state of the resource.",
"details": [
{
"field": "key",
"code": "taken",
"message": "An attribute with this key already exists for this model (id 42). Read it with getCustomAttribute or choose another key.",
"existing_attribute_id": 42
}
]
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "key",
"code": "invalid",
"message": "The key must use only lowercase letters, digits and underscores, for example customer_tax_id."
}
]
}
}{
"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 definition as stored.
One custom attribute definition: a field the account added to conversations, contacts or companies. The AI fill settings and visibility rules are not part of this view.
Kind of value the field holds: text, number, currency, percent, link, date, list (one of the options in values), checkbox or multi_list (several of the options in values).
text, number, currency, percent, link, date, list, checkbox, multi_list "list"
Pattern the text typed into this field has to match, as a plain pattern or a /pattern/flags literal. Cloud Chat enforces it on company values and on the screen and the website chat form; a contact or conversation value written through this API is not checked against it. null when there is none.
"/^[0-9]{11}$/"