Skip to main content
POST
Criar contato (ou reaproveitar o existente)

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 o contato já existe, o nome dele é preservado.

Minimum string length: 1
country_code
string

Código DDI do país (1-3 dígitos). Exemplos: 55 (Brasil), 1 (EUA), 351 (Portugal). Obrigatório quando phone_number é enviado; sem telefone, não envie.

Required string length: 1 - 3
Pattern: ^\d{1,3}$
email
string

Endereço de e-mail do contato. Identifica o contato pela forma normalizada (sem espaços nas pontas, em minúsculas), que é como é gravado. E-mails antigos gravados com maiúscula só são reconhecidos com a mesma grafia, até a normalização da base. Só conta como identificador se tiver "@". Num contato existente, é atualizado quando o contato é achado pelo telefone; achado por e-mail ou LinkedIn, só é preenchido se estiver vazio.

linkedin_identifier
string

Identificador do LinkedIn do contato: URL do perfil ou só o nome do perfil. Exemplo: joao-silva-123. Identifica o contato. Num contato existente, é atualizado quando o contato é achado pelo telefone; achado por e-mail ou LinkedIn, só é preenchido se estiver vazio.

phone_number
string

Número de telefone sem formatação, apenas dígitos (DDD + número, sem o DDI). Exemplo: 11999998888. Identifica o contato. Telefone que não forma um número válido com o country_code é recusado com 400. Opcional: o contato precisa de pelo menos um identificador entre telefone, e-mail e LinkedIn.

Pattern: ^\d*$
job_title
string

Cargo do contato. Exemplo: Gerente de Vendas. Gravado na criação; num contato existente, é atualizado quando o contato é achado pelo telefone; achado por e-mail ou LinkedIn, só é preenchido se estiver vazio.

seniority
string

Nível de senioridade do contato. Exemplo: Senior, Junior, Pleno. Gravado na criação; num contato existente, é atualizado quando o contato é achado pelo telefone; achado por e-mail ou LinkedIn, só é preenchido se estiver vazio.

department
string

Departamento do contato. Exemplo: Comercial, TI, Marketing. Gravado na criação; num contato existente, é atualizado quando o contato é achado pelo telefone; achado por e-mail ou LinkedIn, só é preenchido se estiver vazio.

country
string

País do contato. Exemplo: Brasil. Gravado na criação; num contato existente, é atualizado quando o contato é achado pelo telefone; achado por e-mail ou LinkedIn, só é preenchido se estiver vazio.

region
string

Estado ou região do contato. Exemplo: São Paulo. Gravado na criação; num contato existente, é atualizado quando o contato é achado pelo telefone; achado por e-mail ou LinkedIn, só é preenchido se estiver vazio.

city
string

Cidade do contato. Exemplo: São Paulo. Gravado na criação; num contato existente, é atualizado quando o contato é achado pelo telefone; achado por e-mail ou LinkedIn, só é preenchido se estiver vazio.

experience
string

Experiência profissional do contato. Gravado na criação; num contato existente, é atualizado quando o contato é achado pelo telefone; achado por e-mail ou LinkedIn, só é preenchido se estiver vazio.

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 achado pelo telefone, os slugs enviados são atualizados (merge); achado por e-mail ou LinkedIn, só os slugs vazios são preenchidos. Slugs não enviados ficam como estão. Exemplo: { "cpf": "12345678900", "data_nascimento": "1990-01-15", "valor_total": 1500.50 }

Resposta

Contato existente reaproveitado (created: false). Achado pelo telefone, os campos enviados foram atualizados; por e-mail ou LinkedIn, só os vazios foram preenchidos e ignored_fields lista o que não foi gravado.

name
string
obrigatório

Nome do contato

company
any
obrigatório

Empresa do contato

created
boolean
obrigatório

true quando o contato foi criado (201); false quando foi reaproveitado (200).

matched_by
enum<string> | null
obrigatório

Identificador que casou

Opções disponíveis:
email,
linkedin,
phone
matches_count
number
obrigatório

Quantos contatos da empresa casaram pela chave matched_by (0 ao criar). Acima de 1, a empresa tem contatos duplicados e o mais antigo foi reaproveitado.

ignored_fields
string[]
obrigatório

Campos enviados que NÃO foram gravados porque o contato existente já tinha outro valor (só quando reaproveitado por e-mail ou LinkedIn). Ex.: email, phone_number, job_title, additional_attributes.<slug>. Vazio ao criar e quando achado pelo telefone.

_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