Contacts
Create contact
A number that already belongs to another contact in your company returns 409 (ERR_DUPLICATED_CONTACT).
POST
/
contacts
Create contact
curl --request POST \
--url https://api.connectadesk.com/api/v1/contacts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Marina Alves",
"number": "5511999999999",
"email": "marina@exemplo.com.br",
"code": "CLI-8842",
"origin": "Site",
"cpfcnpj": "12345678909",
"instagramUsername": "marina.alves",
"customFields": [
{
"id": "plano",
"value": "Ouro"
}
],
"sourceUrl": "https://loja.exemplo.com.br/promo",
"sourceId": "23851234567890123",
"headline": "Coleção de inverno",
"utmSource": "instagram",
"utmMedium": "cpc",
"utmCampaign": "inverno-2026",
"utmId": "6543210987"
}
'import requests
url = "https://api.connectadesk.com/api/v1/contacts"
payload = {
"name": "Marina Alves",
"number": "5511999999999",
"email": "marina@exemplo.com.br",
"code": "CLI-8842",
"origin": "Site",
"cpfcnpj": "12345678909",
"instagramUsername": "marina.alves",
"customFields": [
{
"id": "plano",
"value": "Ouro"
}
],
"sourceUrl": "https://loja.exemplo.com.br/promo",
"sourceId": "23851234567890123",
"headline": "Coleção de inverno",
"utmSource": "instagram",
"utmMedium": "cpc",
"utmCampaign": "inverno-2026",
"utmId": "6543210987"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Marina Alves',
number: '5511999999999',
email: 'marina@exemplo.com.br',
code: 'CLI-8842',
origin: 'Site',
cpfcnpj: '12345678909',
instagramUsername: 'marina.alves',
customFields: [{id: 'plano', value: 'Ouro'}],
sourceUrl: 'https://loja.exemplo.com.br/promo',
sourceId: '23851234567890123',
headline: 'Coleção de inverno',
utmSource: 'instagram',
utmMedium: 'cpc',
utmCampaign: 'inverno-2026',
utmId: '6543210987'
})
};
fetch('https://api.connectadesk.com/api/v1/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.connectadesk.com/api/v1/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([
'name' => 'Marina Alves',
'number' => '5511999999999',
'email' => 'marina@exemplo.com.br',
'code' => 'CLI-8842',
'origin' => 'Site',
'cpfcnpj' => '12345678909',
'instagramUsername' => 'marina.alves',
'customFields' => [
[
'id' => 'plano',
'value' => 'Ouro'
]
],
'sourceUrl' => 'https://loja.exemplo.com.br/promo',
'sourceId' => '23851234567890123',
'headline' => 'Coleção de inverno',
'utmSource' => 'instagram',
'utmMedium' => 'cpc',
'utmCampaign' => 'inverno-2026',
'utmId' => '6543210987'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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.connectadesk.com/api/v1/contacts"
payload := strings.NewReader("{\n \"name\": \"Marina Alves\",\n \"number\": \"5511999999999\",\n \"email\": \"marina@exemplo.com.br\",\n \"code\": \"CLI-8842\",\n \"origin\": \"Site\",\n \"cpfcnpj\": \"12345678909\",\n \"instagramUsername\": \"marina.alves\",\n \"customFields\": [\n {\n \"id\": \"plano\",\n \"value\": \"Ouro\"\n }\n ],\n \"sourceUrl\": \"https://loja.exemplo.com.br/promo\",\n \"sourceId\": \"23851234567890123\",\n \"headline\": \"Coleção de inverno\",\n \"utmSource\": \"instagram\",\n \"utmMedium\": \"cpc\",\n \"utmCampaign\": \"inverno-2026\",\n \"utmId\": \"6543210987\"\n}")
req, _ := http.NewRequest("POST", url, payload)
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.connectadesk.com/api/v1/contacts")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Marina Alves\",\n \"number\": \"5511999999999\",\n \"email\": \"marina@exemplo.com.br\",\n \"code\": \"CLI-8842\",\n \"origin\": \"Site\",\n \"cpfcnpj\": \"12345678909\",\n \"instagramUsername\": \"marina.alves\",\n \"customFields\": [\n {\n \"id\": \"plano\",\n \"value\": \"Ouro\"\n }\n ],\n \"sourceUrl\": \"https://loja.exemplo.com.br/promo\",\n \"sourceId\": \"23851234567890123\",\n \"headline\": \"Coleção de inverno\",\n \"utmSource\": \"instagram\",\n \"utmMedium\": \"cpc\",\n \"utmCampaign\": \"inverno-2026\",\n \"utmId\": \"6543210987\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.connectadesk.com/api/v1/contacts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Marina Alves\",\n \"number\": \"5511999999999\",\n \"email\": \"marina@exemplo.com.br\",\n \"code\": \"CLI-8842\",\n \"origin\": \"Site\",\n \"cpfcnpj\": \"12345678909\",\n \"instagramUsername\": \"marina.alves\",\n \"customFields\": [\n {\n \"id\": \"plano\",\n \"value\": \"Ouro\"\n }\n ],\n \"sourceUrl\": \"https://loja.exemplo.com.br/promo\",\n \"sourceId\": \"23851234567890123\",\n \"headline\": \"Coleção de inverno\",\n \"utmSource\": \"instagram\",\n \"utmMedium\": \"cpc\",\n \"utmCampaign\": \"inverno-2026\",\n \"utmId\": \"6543210987\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": 842,
"name": "Maria Silva",
"number": "5511987654321",
"numberCountry": "BR",
"email": "maria.silva@exemplo.com.br",
"code": "CLI-00842",
"cpfCnpj": "12345678909",
"origin": "site",
"profilePicUrl": "https://cdn.exemplo.com/avatars/842.jpg",
"isGroup": false,
"instagramUsername": "maria.silva",
"lid": null,
"sourceUrl": "https://loja.exemplo.com.br/promo",
"sourceId": "23851234567890123",
"headline": "Coleção de inverno",
"mediaType": "image",
"mediaUrl": "https://cdn.exemplo.com/anuncios/inverno.jpg",
"utmSource": "instagram",
"utmMedium": "cpc",
"utmCampaign": "inverno-2026",
"utmId": "6543210987",
"fbclid": "IwAR0xYzAbC123",
"gclid": null,
"ctwaClid": null,
"tags": [
{
"id": 3,
"name": "Cliente VIP",
"color": "#6941C6"
}
],
"customFields": [
{
"key": "plano",
"value": "Ouro",
"customFieldId": 91,
"name": "Plano",
"type": "select"
}
],
"lastChannel": {
"id": 11,
"name": "Instagram Loja",
"type": "instagram"
},
"createdAt": "2026-07-14T13:22:05.412Z",
"updatedAt": "2026-08-18T09:41:17.883Z"
}
}{
"error": {
"code": "ERR_API_VALIDATION",
"message": "O campo `number` é obrigatório."
}
}{
"error": {
"code": "ERR_API_UNAUTHORIZED",
"message": "Token de API ausente ou inválido."
}
}{
"error": {
"code": "ERR_API_FORBIDDEN_SCOPE",
"message": "O token não tem permissão para este método neste módulo. A mensagem real nomeia os dois."
}
}{
"error": {
"code": "ERR_API_IDEMPOTENCY_KEY_REUSED",
"message": "Idempotency-Key já usada com um corpo diferente."
}
}{
"error": {
"code": "ERR_API_VALIDATION",
"message": "O parâmetro `application` é obrigatório e aceita \"contact\" ou \"card\"."
}
}Authorizations
API token in the sk_live_… format.
Headers
Unique key for the operation. If you repeat the call with the same key and the same body, you get the stored response.
Maximum string length:
200Body
application/json
Fields that can be saved on a contact. The photo (profilePicUrl) cannot be changed here, because it comes from the provider (WhatsApp/Instagram) and is updated by it. It is still returned when you read the contact.
Contact name, as it appears in the list and in the ticket.
Example:
"Marina Alves"
Phone number with country and area code. It can be formatted, like +55 (11) 99999-9999, and only the digits are saved. The contact's country (numberCountry) is inferred from the country code, and a number without a valid country code returns 422. It identifies the contact in the upsert and sets the recipient when sending messages.
Example:
"5511999999999"
Contact's email. It is not used for login, since a contact is not a user of the system.
Example:
"marina@exemplo.com.br"
Identifier of the contact in your system. If you fill it in when creating the contact, you can find it again later with GET /contacts?code=..., without relying on the phone number, which can change.
Example:
"CLI-8842"
Where the contact came from. Free text, used in reports.
Example:
"Site"
CPF or CNPJ. Saved exactly as sent, with no formatting applied.
Example:
"12345678909"
Instagram username, without the @.
Example:
"marina.alves"
Custom fields to save. Identify each field by its key, which does not change, while the name can be renamed in the panel at any time.
An empty value removes the field from the contact. Fields that do not appear in the body are left as they are.
The save is all or nothing. If any value fails the type validation, the response is 400 and no field is saved.
Show child attributes
Show child attributes
Page where the contact converted, such as the URL of the ad or the form.
Example:
"https://loja.exemplo.com.br/promo"
Id, at the provider, of the ad or post that brought in the contact.
Example:
"23851234567890123"
Title of the ad or post the contact came from.
Example:
"Coleção de inverno"
utm_source parameter of the source. It is used in the conversations report.
Example:
"instagram"
utm_medium parameter.
Example:
"cpc"
utm_campaign parameter.
Example:
"inverno-2026"
utm_id parameter, when the ad platform sends it.
Example:
"6543210987"
Response
Created
Show child attributes
Show child attributes
Example:
{ "id": 842, "name": "Maria Silva", "number": "5511987654321", "numberCountry": "BR", "email": "maria.silva@exemplo.com.br", "code": "CLI-00842", "cpfCnpj": "12345678909", "origin": "site", "profilePicUrl": "https://cdn.exemplo.com/avatars/842.jpg", "isGroup": false, "instagramUsername": "maria.silva", "lid": null, "sourceUrl": "https://loja.exemplo.com.br/promo", "sourceId": "23851234567890123", "headline": "Coleção de inverno", "mediaType": "image", "mediaUrl": "https://cdn.exemplo.com/anuncios/inverno.jpg", "utmSource": "instagram", "utmMedium": "cpc", "utmCampaign": "inverno-2026", "utmId": "6543210987", "fbclid": "IwAR0xYzAbC123", "gclid": null, "ctwaClid": null, "tags": [ { "id": 3, "name": "Cliente VIP", "color": "#6941C6" } ], "customFields": [ { "key": "plano", "value": "Ouro", "customFieldId": 91, "name": "Plano", "type": "select" } ], "lastChannel": { "id": 11, "name": "Instagram Loja", "type": "instagram" }, "createdAt": "2026-07-14T13:22:05.412Z", "updatedAt": "2026-08-18T09:41:17.883Z" }
⌘I
Create contact
curl --request POST \
--url https://api.connectadesk.com/api/v1/contacts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Marina Alves",
"number": "5511999999999",
"email": "marina@exemplo.com.br",
"code": "CLI-8842",
"origin": "Site",
"cpfcnpj": "12345678909",
"instagramUsername": "marina.alves",
"customFields": [
{
"id": "plano",
"value": "Ouro"
}
],
"sourceUrl": "https://loja.exemplo.com.br/promo",
"sourceId": "23851234567890123",
"headline": "Coleção de inverno",
"utmSource": "instagram",
"utmMedium": "cpc",
"utmCampaign": "inverno-2026",
"utmId": "6543210987"
}
'import requests
url = "https://api.connectadesk.com/api/v1/contacts"
payload = {
"name": "Marina Alves",
"number": "5511999999999",
"email": "marina@exemplo.com.br",
"code": "CLI-8842",
"origin": "Site",
"cpfcnpj": "12345678909",
"instagramUsername": "marina.alves",
"customFields": [
{
"id": "plano",
"value": "Ouro"
}
],
"sourceUrl": "https://loja.exemplo.com.br/promo",
"sourceId": "23851234567890123",
"headline": "Coleção de inverno",
"utmSource": "instagram",
"utmMedium": "cpc",
"utmCampaign": "inverno-2026",
"utmId": "6543210987"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Marina Alves',
number: '5511999999999',
email: 'marina@exemplo.com.br',
code: 'CLI-8842',
origin: 'Site',
cpfcnpj: '12345678909',
instagramUsername: 'marina.alves',
customFields: [{id: 'plano', value: 'Ouro'}],
sourceUrl: 'https://loja.exemplo.com.br/promo',
sourceId: '23851234567890123',
headline: 'Coleção de inverno',
utmSource: 'instagram',
utmMedium: 'cpc',
utmCampaign: 'inverno-2026',
utmId: '6543210987'
})
};
fetch('https://api.connectadesk.com/api/v1/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.connectadesk.com/api/v1/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([
'name' => 'Marina Alves',
'number' => '5511999999999',
'email' => 'marina@exemplo.com.br',
'code' => 'CLI-8842',
'origin' => 'Site',
'cpfcnpj' => '12345678909',
'instagramUsername' => 'marina.alves',
'customFields' => [
[
'id' => 'plano',
'value' => 'Ouro'
]
],
'sourceUrl' => 'https://loja.exemplo.com.br/promo',
'sourceId' => '23851234567890123',
'headline' => 'Coleção de inverno',
'utmSource' => 'instagram',
'utmMedium' => 'cpc',
'utmCampaign' => 'inverno-2026',
'utmId' => '6543210987'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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.connectadesk.com/api/v1/contacts"
payload := strings.NewReader("{\n \"name\": \"Marina Alves\",\n \"number\": \"5511999999999\",\n \"email\": \"marina@exemplo.com.br\",\n \"code\": \"CLI-8842\",\n \"origin\": \"Site\",\n \"cpfcnpj\": \"12345678909\",\n \"instagramUsername\": \"marina.alves\",\n \"customFields\": [\n {\n \"id\": \"plano\",\n \"value\": \"Ouro\"\n }\n ],\n \"sourceUrl\": \"https://loja.exemplo.com.br/promo\",\n \"sourceId\": \"23851234567890123\",\n \"headline\": \"Coleção de inverno\",\n \"utmSource\": \"instagram\",\n \"utmMedium\": \"cpc\",\n \"utmCampaign\": \"inverno-2026\",\n \"utmId\": \"6543210987\"\n}")
req, _ := http.NewRequest("POST", url, payload)
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.connectadesk.com/api/v1/contacts")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Marina Alves\",\n \"number\": \"5511999999999\",\n \"email\": \"marina@exemplo.com.br\",\n \"code\": \"CLI-8842\",\n \"origin\": \"Site\",\n \"cpfcnpj\": \"12345678909\",\n \"instagramUsername\": \"marina.alves\",\n \"customFields\": [\n {\n \"id\": \"plano\",\n \"value\": \"Ouro\"\n }\n ],\n \"sourceUrl\": \"https://loja.exemplo.com.br/promo\",\n \"sourceId\": \"23851234567890123\",\n \"headline\": \"Coleção de inverno\",\n \"utmSource\": \"instagram\",\n \"utmMedium\": \"cpc\",\n \"utmCampaign\": \"inverno-2026\",\n \"utmId\": \"6543210987\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.connectadesk.com/api/v1/contacts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Marina Alves\",\n \"number\": \"5511999999999\",\n \"email\": \"marina@exemplo.com.br\",\n \"code\": \"CLI-8842\",\n \"origin\": \"Site\",\n \"cpfcnpj\": \"12345678909\",\n \"instagramUsername\": \"marina.alves\",\n \"customFields\": [\n {\n \"id\": \"plano\",\n \"value\": \"Ouro\"\n }\n ],\n \"sourceUrl\": \"https://loja.exemplo.com.br/promo\",\n \"sourceId\": \"23851234567890123\",\n \"headline\": \"Coleção de inverno\",\n \"utmSource\": \"instagram\",\n \"utmMedium\": \"cpc\",\n \"utmCampaign\": \"inverno-2026\",\n \"utmId\": \"6543210987\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": 842,
"name": "Maria Silva",
"number": "5511987654321",
"numberCountry": "BR",
"email": "maria.silva@exemplo.com.br",
"code": "CLI-00842",
"cpfCnpj": "12345678909",
"origin": "site",
"profilePicUrl": "https://cdn.exemplo.com/avatars/842.jpg",
"isGroup": false,
"instagramUsername": "maria.silva",
"lid": null,
"sourceUrl": "https://loja.exemplo.com.br/promo",
"sourceId": "23851234567890123",
"headline": "Coleção de inverno",
"mediaType": "image",
"mediaUrl": "https://cdn.exemplo.com/anuncios/inverno.jpg",
"utmSource": "instagram",
"utmMedium": "cpc",
"utmCampaign": "inverno-2026",
"utmId": "6543210987",
"fbclid": "IwAR0xYzAbC123",
"gclid": null,
"ctwaClid": null,
"tags": [
{
"id": 3,
"name": "Cliente VIP",
"color": "#6941C6"
}
],
"customFields": [
{
"key": "plano",
"value": "Ouro",
"customFieldId": 91,
"name": "Plano",
"type": "select"
}
],
"lastChannel": {
"id": 11,
"name": "Instagram Loja",
"type": "instagram"
},
"createdAt": "2026-07-14T13:22:05.412Z",
"updatedAt": "2026-08-18T09:41:17.883Z"
}
}{
"error": {
"code": "ERR_API_VALIDATION",
"message": "O campo `number` é obrigatório."
}
}{
"error": {
"code": "ERR_API_UNAUTHORIZED",
"message": "Token de API ausente ou inválido."
}
}{
"error": {
"code": "ERR_API_FORBIDDEN_SCOPE",
"message": "O token não tem permissão para este método neste módulo. A mensagem real nomeia os dois."
}
}{
"error": {
"code": "ERR_API_IDEMPOTENCY_KEY_REUSED",
"message": "Idempotency-Key já usada com um corpo diferente."
}
}{
"error": {
"code": "ERR_API_VALIDATION",
"message": "O parâmetro `application` é obrigatório e aceita \"contact\" ou \"card\"."
}
}