number (E.164 sem +). O upsert usa esse número como chave — rodar a mesma chamada duas vezes não duplica o contato.
1
Crie ou atualize por número (upsert)
POST /v1/contacts requer escopo contacts:write. Se o number já existe, os campos enviados sobrescrevem os atuais e a resposta vem com 200 e created: false; se não existe, cria e responde 201 com created: true.Rodar essa mesma chamada de novo não cria um segundo contato — é seguro reenviar em caso de timeout ou retry da sua integração.
2
Campos customizados com extraInfo
Use
extraInfo para dados que não têm campo próprio (plano contratado, ID no seu CRM, etc.). É uma lista de { name, value } — ambos string:extraInfo só volta no GET /v1/contacts/{contactId} de um contato específico — a listagem (GET /v1/contacts) não traz esse campo, pra manter a resposta enxuta.3
Número é imutável
PUT /v1/contacts/{contactId} atualiza name, email, document, disableBot e extraInfo — mas não aceita number. Enviar number no corpo devolve 400 ERR_NUMBER_IMMUTABLE. Pra corrigir um número errado, use o painel.Fluxo guiado: segmentar “lead contatado”
Um caso comum: marcar quem já recebeu uma campanha e depois filtrar só quem ainda não foi contatado.1
Crie a tag no painel
Tags são criadas em Tags (menu lateral) — não existe endpoint de criação de tag na API pública, só leitura e sincronização no contato.
2
Descubra o ID da tag
id da tag “lead-contatado” na resposta (tags[].id).3
Aplique a tag no contato
PUT /v1/contacts/{contactId}/tags substitui todas as tags do contato — não é um “adicionar”, é uma sincronização completa. Envie a lista final de IDs:4
Filtre quem ainda não foi contatado
GET /v1/contacts filtra por tagId (contato com qualquer uma das tags listadas). Para excluir quem já tem a tag, use o filtro equivalente em GET /v1/cards, que tem notContactTagId (exclui pelo contato do card). Se seu caso é sobre contatos e não cards, busque todos e filtre no seu lado, ou inverta a lógica: tagueie os “não contatados” em vez dos “contatados”.Erros comuns
Veja o catálogo completo de erros.