curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"contact": {
"name": "Maria Silva",
"email": "maria.silva@example.com",
"phone_number": "+5511987654321",
"identifier": "crm-4821",
"custom_attributes": {
"plan": "pro"
}
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts"
payload = { "contact": {
"name": "Maria Silva",
"email": "maria.silva@example.com",
"phone_number": "+5511987654321",
"identifier": "crm-4821",
"custom_attributes": { "plan": "pro" }
} }
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({
contact: {
name: 'Maria Silva',
email: 'maria.silva@example.com',
phone_number: '+5511987654321',
identifier: 'crm-4821',
custom_attributes: {plan: 'pro'}
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts', 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",
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([
'contact' => [
'name' => 'Maria Silva',
'email' => 'maria.silva@example.com',
'phone_number' => '+5511987654321',
'identifier' => 'crm-4821',
'custom_attributes' => [
'plan' => 'pro'
]
]
]),
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}/contacts"
payload := strings.NewReader("{\n \"contact\": {\n \"name\": \"Maria Silva\",\n \"email\": \"maria.silva@example.com\",\n \"phone_number\": \"+5511987654321\",\n \"identifier\": \"crm-4821\",\n \"custom_attributes\": {\n \"plan\": \"pro\"\n }\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}/contacts")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"contact\": {\n \"name\": \"Maria Silva\",\n \"email\": \"maria.silva@example.com\",\n \"phone_number\": \"+5511987654321\",\n \"identifier\": \"crm-4821\",\n \"custom_attributes\": {\n \"plan\": \"pro\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts")
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 \"contact\": {\n \"name\": \"Maria Silva\",\n \"email\": \"maria.silva@example.com\",\n \"phone_number\": \"+5511987654321\",\n \"identifier\": \"crm-4821\",\n \"custom_attributes\": {\n \"plan\": \"pro\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"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"
}{
"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": "conflict",
"message": "Conflict",
"details": [
{
"field": "email",
"code": "duplicate",
"message": "Another contact in this account already has this email; its id is 815. Nothing was created: call updateContact with that id to change it.",
"existing_contact_id": 815
}
]
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "email",
"code": "invalid",
"message": "is invalid"
}
]
}
}{
"message": "API rate limit exceeded"
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}Create a contact
Creates a contact. name is required; email, phone_number, identifier and custom_attributes are optional. The body is wrapped in contact.
Before anything is written, the account is checked for a contact with the same email address (ignoring case), the same phone number (a Brazilian number with or without the ninth digit is the same number) or the same identifier. If one exists, nothing is created and the response is a 409 whose error.details[0].existing_contact_id is the id of the contact that already exists: update that contact instead of retrying.
email must be a valid address and is stored in lower case. phone_number is stored in E.164 (for example +5511987654321): send it with + and the country code. Digits without + that look like a Brazilian area code plus number are read as Brazilian and stored with +55.
A contact created with no email, phone number or identifier is stored, but search contacts does not return it, so keep the id from the response. The new contact is not attached to any inbox or conversation.
Only account administrators can create contacts through this API.
curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"contact": {
"name": "Maria Silva",
"email": "maria.silva@example.com",
"phone_number": "+5511987654321",
"identifier": "crm-4821",
"custom_attributes": {
"plan": "pro"
}
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts"
payload = { "contact": {
"name": "Maria Silva",
"email": "maria.silva@example.com",
"phone_number": "+5511987654321",
"identifier": "crm-4821",
"custom_attributes": { "plan": "pro" }
} }
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({
contact: {
name: 'Maria Silva',
email: 'maria.silva@example.com',
phone_number: '+5511987654321',
identifier: 'crm-4821',
custom_attributes: {plan: 'pro'}
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts', 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",
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([
'contact' => [
'name' => 'Maria Silva',
'email' => 'maria.silva@example.com',
'phone_number' => '+5511987654321',
'identifier' => 'crm-4821',
'custom_attributes' => [
'plan' => 'pro'
]
]
]),
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}/contacts"
payload := strings.NewReader("{\n \"contact\": {\n \"name\": \"Maria Silva\",\n \"email\": \"maria.silva@example.com\",\n \"phone_number\": \"+5511987654321\",\n \"identifier\": \"crm-4821\",\n \"custom_attributes\": {\n \"plan\": \"pro\"\n }\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}/contacts")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"contact\": {\n \"name\": \"Maria Silva\",\n \"email\": \"maria.silva@example.com\",\n \"phone_number\": \"+5511987654321\",\n \"identifier\": \"crm-4821\",\n \"custom_attributes\": {\n \"plan\": \"pro\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/contacts")
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 \"contact\": {\n \"name\": \"Maria Silva\",\n \"email\": \"maria.silva@example.com\",\n \"phone_number\": \"+5511987654321\",\n \"identifier\": \"crm-4821\",\n \"custom_attributes\": {\n \"plan\": \"pro\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"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"
}{
"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": "conflict",
"message": "Conflict",
"details": [
{
"field": "email",
"code": "duplicate",
"message": "Another contact in this account already has this email; its id is 815. Nothing was created: call updateContact with that id to change it.",
"existing_contact_id": 815
}
]
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "email",
"code": "invalid",
"message": "is invalid"
}
]
}
}{
"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
Response
Created. The body is the contact itself, not wrapped in data.
A customer contact of the account.