curl --request PUT \
--url https://api.nuvia.ai/v1/contacts/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"country_code": "<string>",
"email": "<string>",
"linkedin_identifier": "<string>",
"phone_number": "<string>",
"job_title": "<string>",
"seniority": "<string>",
"department": "<string>",
"country": "<string>",
"region": "<string>",
"city": "<string>",
"experience": "<string>",
"skills": "<string>",
"additional_attributes": {},
"custom_fields": {},
"business": "<string>"
}
'import requests
url = "https://api.nuvia.ai/v1/contacts/{id}"
payload = {
"name": "<string>",
"country_code": "<string>",
"email": "<string>",
"linkedin_identifier": "<string>",
"phone_number": "<string>",
"job_title": "<string>",
"seniority": "<string>",
"department": "<string>",
"country": "<string>",
"region": "<string>",
"city": "<string>",
"experience": "<string>",
"skills": "<string>",
"additional_attributes": {},
"custom_fields": {},
"business": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
country_code: '<string>',
email: '<string>',
linkedin_identifier: '<string>',
phone_number: '<string>',
job_title: '<string>',
seniority: '<string>',
department: '<string>',
country: '<string>',
region: '<string>',
city: '<string>',
experience: '<string>',
skills: '<string>',
additional_attributes: {},
custom_fields: {},
business: '<string>'
})
};
fetch('https://api.nuvia.ai/v1/contacts/{id}', 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.nuvia.ai/v1/contacts/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'country_code' => '<string>',
'email' => '<string>',
'linkedin_identifier' => '<string>',
'phone_number' => '<string>',
'job_title' => '<string>',
'seniority' => '<string>',
'department' => '<string>',
'country' => '<string>',
'region' => '<string>',
'city' => '<string>',
'experience' => '<string>',
'skills' => '<string>',
'additional_attributes' => [
],
'custom_fields' => [
],
'business' => '<string>'
]),
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.nuvia.ai/v1/contacts/{id}"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"country_code\": \"<string>\",\n \"email\": \"<string>\",\n \"linkedin_identifier\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"job_title\": \"<string>\",\n \"seniority\": \"<string>\",\n \"department\": \"<string>\",\n \"country\": \"<string>\",\n \"region\": \"<string>\",\n \"city\": \"<string>\",\n \"experience\": \"<string>\",\n \"skills\": \"<string>\",\n \"additional_attributes\": {},\n \"custom_fields\": {},\n \"business\": \"<string>\"\n}")
req, _ := http.NewRequest("PUT", 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.put("https://api.nuvia.ai/v1/contacts/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"country_code\": \"<string>\",\n \"email\": \"<string>\",\n \"linkedin_identifier\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"job_title\": \"<string>\",\n \"seniority\": \"<string>\",\n \"department\": \"<string>\",\n \"country\": \"<string>\",\n \"region\": \"<string>\",\n \"city\": \"<string>\",\n \"experience\": \"<string>\",\n \"skills\": \"<string>\",\n \"additional_attributes\": {},\n \"custom_fields\": {},\n \"business\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nuvia.ai/v1/contacts/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"country_code\": \"<string>\",\n \"email\": \"<string>\",\n \"linkedin_identifier\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"job_title\": \"<string>\",\n \"seniority\": \"<string>\",\n \"department\": \"<string>\",\n \"country\": \"<string>\",\n \"region\": \"<string>\",\n \"city\": \"<string>\",\n \"experience\": \"<string>\",\n \"skills\": \"<string>\",\n \"additional_attributes\": {},\n \"custom_fields\": {},\n \"business\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"name": "<string>",
"company": "<unknown>",
"_id": "<string>",
"id": "<string>",
"country_code": "<string>",
"email": "<string>",
"last_activity_at": "<unknown>",
"phone_number": "<string>",
"linkedin_identifier": "<string>",
"job_title": "<string>",
"seniority": "<string>",
"department": "<string>",
"country": "<string>",
"region": "<string>",
"city": "<string>",
"experience": "<string>",
"skills": "<string>",
"additional_attributes": {},
"business": "<string>",
"notes": [
{
"_id": "<string>",
"content": "<string>",
"user": "<string>",
"createdAt": "<unknown>",
"updatedAt": "<unknown>"
}
],
"marketing_opt_out": {},
"do_not_contact": {
"reason": "UNSUBSCRIBE_REQUESTED",
"marked_by": {
"type": "USER",
"id": "<string>",
"name": "<string>"
},
"marked_at": "2023-11-07T05:31:56Z",
"note": "<string>",
"source_conversation_id": "<string>",
"block_id": "<string>",
"origin_contact_id": "<string>"
},
"whatsapp_user_id": "<string>",
"whatsapp_username": "<string>",
"whatsapp_parent_user_id": "<string>",
"createdAt": "<unknown>",
"updatedAt": "<unknown>"
}{
"statusCode": 123,
"code": "CONTACT_IDENTITY_CONFLICT",
"message": "<string>",
"conflicts": [
{
"field": "email",
"contact": {
"_id": "<string>",
"name": "<string>",
"email": "<string>",
"phone_number": "<string>",
"country_code": "<string>",
"linkedin_identifier": "<string>"
}
}
]
}Atualizar contato
Atualiza os campos enviados de um contato existente. Campos ausentes não são alterados.
- additional_attributes:
{ "slug": valor }, com valor primitivo (string, number, boolean ou null). Faz merge com os valores atuais. Slug inexistente, ou de custom field com contexto diferente de CONTACT, é ignorado em silêncio, sem erro. - custom_fields:
{ "slug": valor }para camposselect(option_id),multi_select(lista de option_id) etext. A validação é atômica: se algum valor for inválido, nenhum custom field é gravado. Slug inexistente retorna 404 e opção inválida retorna 422. Paranumberedate, useadditional_attributes. - custom_fields e additional_attributes juntos: envie em requisições separadas. No mesmo payload, a gravação de
additional_attributessobrescreve a decustom_fields. - Telefone:
phone_numberecountry_codepodem ser trocados. O número novo é normalizado e, se for inválido, retorna 400. - Identificador de outro contato: gravar
email,linkedin_identifierou telefone que já pertence a OUTRO contato da empresa retorna 409CONTACT_IDENTIFIER_TAKEN(ex.:"O e-mail já pertence a outro contato."), com o contato dono do dado emconflicts. Valor igual ao que o próprio contato já tem não é conflito. - Último identificador: remover o último entre telefone, e-mail e LinkedIn retorna 400
"O contato precisa de pelo menos um identificador.".
curl --request PUT \
--url https://api.nuvia.ai/v1/contacts/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"country_code": "<string>",
"email": "<string>",
"linkedin_identifier": "<string>",
"phone_number": "<string>",
"job_title": "<string>",
"seniority": "<string>",
"department": "<string>",
"country": "<string>",
"region": "<string>",
"city": "<string>",
"experience": "<string>",
"skills": "<string>",
"additional_attributes": {},
"custom_fields": {},
"business": "<string>"
}
'import requests
url = "https://api.nuvia.ai/v1/contacts/{id}"
payload = {
"name": "<string>",
"country_code": "<string>",
"email": "<string>",
"linkedin_identifier": "<string>",
"phone_number": "<string>",
"job_title": "<string>",
"seniority": "<string>",
"department": "<string>",
"country": "<string>",
"region": "<string>",
"city": "<string>",
"experience": "<string>",
"skills": "<string>",
"additional_attributes": {},
"custom_fields": {},
"business": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
country_code: '<string>',
email: '<string>',
linkedin_identifier: '<string>',
phone_number: '<string>',
job_title: '<string>',
seniority: '<string>',
department: '<string>',
country: '<string>',
region: '<string>',
city: '<string>',
experience: '<string>',
skills: '<string>',
additional_attributes: {},
custom_fields: {},
business: '<string>'
})
};
fetch('https://api.nuvia.ai/v1/contacts/{id}', 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.nuvia.ai/v1/contacts/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'country_code' => '<string>',
'email' => '<string>',
'linkedin_identifier' => '<string>',
'phone_number' => '<string>',
'job_title' => '<string>',
'seniority' => '<string>',
'department' => '<string>',
'country' => '<string>',
'region' => '<string>',
'city' => '<string>',
'experience' => '<string>',
'skills' => '<string>',
'additional_attributes' => [
],
'custom_fields' => [
],
'business' => '<string>'
]),
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.nuvia.ai/v1/contacts/{id}"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"country_code\": \"<string>\",\n \"email\": \"<string>\",\n \"linkedin_identifier\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"job_title\": \"<string>\",\n \"seniority\": \"<string>\",\n \"department\": \"<string>\",\n \"country\": \"<string>\",\n \"region\": \"<string>\",\n \"city\": \"<string>\",\n \"experience\": \"<string>\",\n \"skills\": \"<string>\",\n \"additional_attributes\": {},\n \"custom_fields\": {},\n \"business\": \"<string>\"\n}")
req, _ := http.NewRequest("PUT", 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.put("https://api.nuvia.ai/v1/contacts/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"country_code\": \"<string>\",\n \"email\": \"<string>\",\n \"linkedin_identifier\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"job_title\": \"<string>\",\n \"seniority\": \"<string>\",\n \"department\": \"<string>\",\n \"country\": \"<string>\",\n \"region\": \"<string>\",\n \"city\": \"<string>\",\n \"experience\": \"<string>\",\n \"skills\": \"<string>\",\n \"additional_attributes\": {},\n \"custom_fields\": {},\n \"business\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nuvia.ai/v1/contacts/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"country_code\": \"<string>\",\n \"email\": \"<string>\",\n \"linkedin_identifier\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"job_title\": \"<string>\",\n \"seniority\": \"<string>\",\n \"department\": \"<string>\",\n \"country\": \"<string>\",\n \"region\": \"<string>\",\n \"city\": \"<string>\",\n \"experience\": \"<string>\",\n \"skills\": \"<string>\",\n \"additional_attributes\": {},\n \"custom_fields\": {},\n \"business\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"name": "<string>",
"company": "<unknown>",
"_id": "<string>",
"id": "<string>",
"country_code": "<string>",
"email": "<string>",
"last_activity_at": "<unknown>",
"phone_number": "<string>",
"linkedin_identifier": "<string>",
"job_title": "<string>",
"seniority": "<string>",
"department": "<string>",
"country": "<string>",
"region": "<string>",
"city": "<string>",
"experience": "<string>",
"skills": "<string>",
"additional_attributes": {},
"business": "<string>",
"notes": [
{
"_id": "<string>",
"content": "<string>",
"user": "<string>",
"createdAt": "<unknown>",
"updatedAt": "<unknown>"
}
],
"marketing_opt_out": {},
"do_not_contact": {
"reason": "UNSUBSCRIBE_REQUESTED",
"marked_by": {
"type": "USER",
"id": "<string>",
"name": "<string>"
},
"marked_at": "2023-11-07T05:31:56Z",
"note": "<string>",
"source_conversation_id": "<string>",
"block_id": "<string>",
"origin_contact_id": "<string>"
},
"whatsapp_user_id": "<string>",
"whatsapp_username": "<string>",
"whatsapp_parent_user_id": "<string>",
"createdAt": "<unknown>",
"updatedAt": "<unknown>"
}{
"statusCode": 123,
"code": "CONTACT_IDENTITY_CONFLICT",
"message": "<string>",
"conflicts": [
{
"field": "email",
"contact": {
"_id": "<string>",
"name": "<string>",
"email": "<string>",
"phone_number": "<string>",
"country_code": "<string>",
"linkedin_identifier": "<string>"
}
}
]
}Autorizações
Token JWT de autenticação
Cabeçalhos
Identificador da empresa-alvo. Obrigatório apenas para API Keys globais (type=global). Ignorado para API Keys de empresa e usuários humanos.
Parâmetros de caminho
ID do contato
Corpo
Nome completo do contato. Campo opcional na atualização.
Código DDI do país (1-3 dígitos). Exemplos: 55 (Brasil), 1 (EUA), 351 (Portugal).
Endereço de e-mail do contato. E-mail que já pertence a outro contato da empresa retorna 409.
Identificador do perfil LinkedIn do contato (URL ou nome do perfil). LinkedIn que já pertence a outro contato da empresa retorna 409.
Número de telefone sem formatação, apenas dígitos (DDD + número, sem o DDI). Exemplo: 11999998888. O número é normalizado; se for inválido, retorna 400. Telefone que já pertence a outro contato da empresa retorna 409.
Cargo do contato. Exemplo: Gerente de Vendas.
Nível de senioridade do contato. Exemplo: Senior, Junior, Pleno.
Departamento do contato. Exemplo: Comercial, TI, Marketing.
País do contato. Exemplo: Brasil.
Estado ou região do contato. Exemplo: São Paulo.
Cidade do contato. Exemplo: São Paulo.
Experiência profissional do contato.
Habilidades do contato.
Campos personalizados do contato. Formato: { "slug_do_campo": valor }. Os slugs devem corresponder a custom fields cadastrados com contexto CONTACT. Slugs inválidos ou inexistentes são ignorados silenciosamente. Os valores são mesclados com os atributos existentes (merge), não substitui todo o objeto. Os valores devem ser primitivos (string, number, boolean ou null). Exemplo: { "cpf": "12345678900", "valor_total": 2500.00 }
Show child attributes
Show child attributes
Atualiza valores de campos customizados do contato, por slug. Cobre select ({ "slug": "<option_id>" }), multi_select ({ "slug": ["", ""] }) e text ({ "slug": "valor" }). Para number/date, use additional_attributes, que preserva o tipo nativo. Validação atômica: se algum valor é inválido, nenhum custom field é gravado. Slug sem custom field correspondente retorna 404; opção inválida retorna 422; valor não textual em campo text retorna 400. Não envie junto com additional_attributes no mesmo payload: a gravação de additional_attributes sobrescreve a de custom_fields. Os option_id saem de GET /v1/custom-fields/{id}/options.
Show child attributes
Show child attributes
ID do Business ao qual o contato pertence (null para remover).
Resposta
Contato atualizado com sucesso
Nome do contato
Empresa do contato
ID do contato
ID do contato (mesmo valor de _id)
Código do país do número. Ausente junto com o telefone quando o contato só tem identificador do WhatsApp.
E-mail do contato
Data da última atividade do contato
Número de telefone do contato. Ausente quando o contato só tem identificador do WhatsApp.
Identificador do perfil do LinkedIn
Cargo do contato
Nível de senioridade do contato
Departamento do contato
País do contato
Estado ou região do contato
Cidade do contato
Experiência profissional do contato
Habilidades do contato
Valores dos campos personalizados do contato, por slug. Gravado via additional_attributes, o valor vem no envelope { id, value, type, updatedAt }. Gravado via custom_fields (PUT), vem cru: o option_id (select), a lista de option_id (multi_select) ou o texto (text).
Show child attributes
Show child attributes
ID do Business ao qual o contato pertence
Notas registradas no contato
Show child attributes
Show child attributes
Opt-out de marketing por meio de comunicação (whatsapp, email, linkedin). Ausente ou vazio quando o contato não pediu para sair de nenhum meio.
Show child attributes
Show child attributes
Estado "Não abordar": objeto enquanto bloqueado, null depois do desbloqueio, ausente em quem nunca foi marcado. Bloqueia todo envio automático, em todos os canais.
Show child attributes
Show child attributes
Identificador do contato no WhatsApp (BSUID), atribuído pela Meta. String opaca.
@username do contato no WhatsApp, como a Meta envia
parent_user_id do contato no WhatsApp, como a Meta envia
Data de criação do contato
Data de atualização do contato