curl --request POST \
--url https://api.cloudtalk.io/v1/contacts/{contactId}/tags \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"tagIds": [
"123",
"131"
]
}
'import requests
url = "https://api.cloudtalk.io/v1/contacts/{contactId}/tags"
payload = { "tagIds": ["123", "131"] }
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({tagIds: ['123', '131']})
};
fetch('https://api.cloudtalk.io/v1/contacts/{contactId}/tags', 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.cloudtalk.io/v1/contacts/{contactId}/tags",
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([
'tagIds' => [
'123',
'131'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$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.cloudtalk.io/v1/contacts/{contactId}/tags"
payload := strings.NewReader("{\n \"tagIds\": [\n \"123\",\n \"131\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
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.cloudtalk.io/v1/contacts/{contactId}/tags")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"tagIds\": [\n \"123\",\n \"131\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudtalk.io/v1/contacts/{contactId}/tags")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"tagIds\": [\n \"123\",\n \"131\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "44210",
"type": "contact",
"name": "Jane Doe",
"title": "Head of Procurement",
"company": "Acme Inc.",
"industry": "Manufacturing",
"website": "https://acme.example.com",
"address": "1 Market Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": {
"code": "US",
"name": "United States"
},
"phones": [
"+12025550143",
"+13105550166"
],
"emails": [
"[email protected]"
],
"tags": [
{
"id": "123",
"name": "vip",
"readOnly": false
},
{
"id": "131",
"name": "webinar",
"readOnly": false
}
],
"customFields": {
"Segment": "enterprise"
},
"favoriteUserId": "7",
"source": "api",
"createdAt": "2026-08-17T09:34:21Z",
"updatedAt": "2026-11-02T10:25:00Z",
"dashboardUrl": "https://dashboard.cloudtalk.io/menu/contacts/details/44210"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"code": "UNAUTHORIZED",
"message": "You are not authorized to access this resource."
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}<string>{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}Add tags to a contact
Adds contact tags to the contact and returns the updated contact. Tags the contact already has are ignored, so a repeated request is safe and changes nothing. Only the tags you send are written: a request running at the same time that adds or removes other tags is not undone by this one.
When at least one tag changed, updatedAt moves forward and contact.updated is sent, and CloudTalk exports the change to your active CRM integrations. Dialer campaigns that target these tags pick the contact up, usually within a minute and at most within one Dialer reconcile (5 minutes by default).
Read-only tags cannot be added (see List contact tags).
curl --request POST \
--url https://api.cloudtalk.io/v1/contacts/{contactId}/tags \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"tagIds": [
"123",
"131"
]
}
'import requests
url = "https://api.cloudtalk.io/v1/contacts/{contactId}/tags"
payload = { "tagIds": ["123", "131"] }
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({tagIds: ['123', '131']})
};
fetch('https://api.cloudtalk.io/v1/contacts/{contactId}/tags', 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.cloudtalk.io/v1/contacts/{contactId}/tags",
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([
'tagIds' => [
'123',
'131'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$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.cloudtalk.io/v1/contacts/{contactId}/tags"
payload := strings.NewReader("{\n \"tagIds\": [\n \"123\",\n \"131\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
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.cloudtalk.io/v1/contacts/{contactId}/tags")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"tagIds\": [\n \"123\",\n \"131\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudtalk.io/v1/contacts/{contactId}/tags")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"tagIds\": [\n \"123\",\n \"131\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "44210",
"type": "contact",
"name": "Jane Doe",
"title": "Head of Procurement",
"company": "Acme Inc.",
"industry": "Manufacturing",
"website": "https://acme.example.com",
"address": "1 Market Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": {
"code": "US",
"name": "United States"
},
"phones": [
"+12025550143",
"+13105550166"
],
"emails": [
"[email protected]"
],
"tags": [
{
"id": "123",
"name": "vip",
"readOnly": false
},
{
"id": "131",
"name": "webinar",
"readOnly": false
}
],
"customFields": {
"Segment": "enterprise"
},
"favoriteUserId": "7",
"source": "api",
"createdAt": "2026-08-17T09:34:21Z",
"updatedAt": "2026-11-02T10:25:00Z",
"dashboardUrl": "https://dashboard.cloudtalk.io/menu/contacts/details/44210"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"code": "UNAUTHORIZED",
"message": "You are not authorized to access this resource."
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}<string>{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}Authorizations
HTTP Basic Authentication. Use your API Access Key ID as the username and your API Access Key Secret as the password. Generate keys in the CloudTalk Dashboard under Account -> Settings -> API Keys (https://dashboard.cloudtalk.io/menu/account/settings/API-keys).
Body
Response
The contact, with its tags after the change.
A contact or lead, with every number, email, tag and custom field.
Link to the contact's page in the CloudTalk Dashboard. It carries no credentials: the person must be signed in to your company's Dashboard, and your company must have Contacts in its menu, otherwise the Dashboard opens their default page. Read-only.
"https://dashboard.cloudtalk.io/menu/contacts/details/44210"