Skip to main content
POST
Criar ou atualizar contato

Autorizações

Authorization
string
header
obrigatório

Token JWT de autenticação

Cabeçalhos

x-company-id
string

Identificador da empresa-alvo. Obrigatório apenas para API Keys globais (type=global). Ignorado para API Keys de empresa e usuários humanos.

Corpo

application/json
name
string
obrigatório

Nome completo do contato. Campo obrigatório. Se já existe contato com o mesmo telefone, o nome dele é preservado.

Minimum string length: 1
country_code
string
obrigatório

Código DDI do país (1-3 dígitos). Exemplos: 55 (Brasil), 1 (EUA), 351 (Portugal). Junto com phone_number, identifica o contato: se já existe contato da empresa com esse telefone, ele é atualizado em vez de criado.

Required string length: 1 - 3
Pattern: ^\d{1,3}$
phone_number
string
obrigatório

Número de telefone sem formatação, apenas dígitos (DDD + número, sem o DDI). Exemplo: 11999998888. Telefone que não forma um número válido com o country_code é recusado com 400.

Minimum string length: 1
Pattern: ^\d+$
email
string

Endereço de e-mail do contato. Campo opcional. Não é usado para encontrar o contato; num contato existente, substitui o e-mail atual.

linkedin_identifier
string

Identificador do LinkedIn do contato (nome do perfil). Exemplo: joao-silva-123. Não é usado para encontrar o contato; num contato existente, substitui o valor atual.

job_title
string

Cargo do contato. Exemplo: Gerente de Vendas. Gravado na criação; num contato existente, atualizado quando enviado.

seniority
string

Nível de senioridade do contato. Exemplo: Senior, Junior, Pleno. Gravado na criação; num contato existente, atualizado quando enviado.

department
string

Departamento do contato. Exemplo: Comercial, TI, Marketing. Gravado na criação; num contato existente, atualizado quando enviado.

country
string

País do contato. Exemplo: Brasil. Gravado na criação; num contato existente, atualizado quando enviado.

region
string

Estado ou região do contato. Exemplo: São Paulo. Gravado na criação; num contato existente, atualizado quando enviado.

city
string

Cidade do contato. Exemplo: São Paulo. Gravado na criação; num contato existente, atualizado quando enviado.

experience
string

Experiência profissional do contato. Gravado na criação; num contato existente, atualizado quando enviado.

additional_attributes
object

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 devem ser primitivos (string, number, boolean ou null). Num contato existente, só os slugs enviados são atualizados (merge); os demais ficam como estão. Exemplo: { "cpf": "12345678900", "data_nascimento": "1990-01-15", "valor_total": 1500.50 }

Resposta

Contato criado, ou contato existente com o mesmo telefone atualizado

name
string
obrigatório

Nome do contato

company
any
obrigatório

Empresa do contato

_id
string

ID do contato

id
string

ID do contato (mesmo valor de _id)

country_code
string

Código do país do número. Ausente junto com o telefone quando o contato só tem identificador do WhatsApp.

email
string

E-mail do contato

last_activity_at
any

Data da última atividade do contato

phone_number
string

Número de telefone do contato. Ausente quando o contato só tem identificador do WhatsApp.

linkedin_identifier
string

Identificador do perfil do LinkedIn

job_title
string

Cargo do contato

seniority
string

Nível de senioridade do contato

department
string

Departamento do contato

country
string

País do contato

region
string

Estado ou região do contato

city
string

Cidade do contato

experience
string

Experiência profissional do contato

skills
string

Habilidades do contato

additional_attributes
object

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).

business
string | null

ID do Business ao qual o contato pertence

notes
object[]

Notas registradas no contato

marketing_opt_out
object

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.

whatsapp_user_id
string

Identificador do contato no WhatsApp (BSUID), atribuído pela Meta. String opaca.

whatsapp_username
string

@username do contato no WhatsApp, como a Meta envia

whatsapp_parent_user_id
string

parent_user_id do contato no WhatsApp, como a Meta envia

createdAt
any

Data de criação do contato

updatedAt
any

Data de atualização do contato