Atualizar contato

Endpoint

PATCH /v1/contacts/:id

Escopo necessário: write:contacts Envie apenas os campos que deseja alterar. Campos não incluídos no corpo permanecem inalterados.

Parâmetros de path

Parâmetro	Tipo	Descrição
`id`	string	ID do contato

Corpo da requisição

Campo	Tipo	Descrição
`name`	string	Nome completo
`email`	string\|null	Email (envie `null` para limpar)
`phone`	string\|null	Telefone (envie `null` para limpar). Ao alterar o número, a SocialSell atualiza automaticamente a identidade usada pelo WhatsApp
`instagram_username`	string\|null	Username do Instagram
`messenger_psid`	string\|null	PSID do Messenger
`company_id`	string\|null	ID da empresa (envie `null` para desvincular)
`external_id`	string\|null	Identificador no seu sistema, até 100 caracteres (envie `null` para limpar)
`tags`	string[]	Substitui completamente a lista de tags
`custom_fields`	object	Substitui completamente os campos personalizados
`funnel_stage`	string\|null	Descontinuado — aceito e ignorado; a resposta devolve sempre `null`
`marketing_consent`	object	Autorização para mensagens de marketing: `{ given, method?, source }`. Veja Marketing
`marketing_opt_out`	object	Descadastro de mensagens de marketing: `{ opted_out, reason? }`. Veja Marketing

Exemplo de requisição

curl -X PATCH https://api.socialsell.ai/v1/contacts/664f1a2b3c4d5e6f78901234 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "novo@email.com.br",
    "tags": ["cliente", "vip", "enterprise"]
  }'

Exemplo de resposta

{
  "data": {
    "id": "664f1a2b3c4d5e6f78901234",
    "name": "João Silva",
    "email": "novo@email.com.br",
    "tags": ["cliente", "vip", "enterprise"],
    "updated_at": "2026-06-10T16:00:00.000Z"
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6a7b8"
  }
}

A atualização dispara o evento contact.updated em webhooks configurados.

Os campos tags e custom_fields substituem os valores anteriores por completo. Para adicionar uma tag sem perder as existentes, use o endpoint dedicado Adicionar tag.

Marketing

Os campos têm o mesmo formato de Criar contato:

marketing_consent registra a autorização que você coletou fora da SocialSell, como o aceite no formulário do seu site. source é obrigatório com given: true; method padrão é form. Enviar a mesma autorização de novo não grava nada e preserva a data original. given: false remove a autorização.
marketing_opt_out registra o descadastro com origem api. O descadastro vence a autorização: o contato fica fora de todo envio promocional, mesmo autorizado. Registrar autorização não desfaz um descadastro — para isso envie opted_out: false.

Quando o próprio cliente desligou as promoções pelo WhatsApp (opt_out.source igual a meta_preference ou meta_error_131050), só ele pode reativar, pelo próprio WhatsApp. opted_out: false nesse caso devolve 409 OPT_OUT_LOCKED e nada do corpo é gravado.

curl -X PATCH https://api.socialsell.ai/v1/contacts/664f1a2b3c4d5e6f78901234 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "marketing_opt_out": { "opted_out": true, "reason": "Pediu por e-mail" }
  }'

Cada mudança entra no histórico do contato, e o contact.updated traz marketing em changed_fields.

Erros

Código	Status	Descrição
`INVALID_ID`	`400`	ID com formato inválido
`VALIDATION_ERROR`	`400`	`external_id` fora do formato, ou `marketing_consent`/`marketing_opt_out` inválido. O corpo traz `details[]` com `field` e `message`
`NOT_FOUND`	`404`	Contato não encontrado
`DUPLICATE_EXTERNAL_ID`	`409`	O `external_id` já pertence a outro contato da organização
`OPT_OUT_LOCKED`	`409`	Tentativa de desfazer um descadastro que o próprio cliente fez pelo WhatsApp

Contatos

Empresas

Negócios

Funis de venda

Conversas

Mensagens

Tarefas

Campos personalizados

Agentes de IA

Disparos

Créditos de mensagem

Lookup

Endpoint

Parâmetros de path

Corpo da requisição

Exemplo de requisição

Exemplo de resposta

Marketing

Erros

​Endpoint

​Parâmetros de path

​Corpo da requisição

​Exemplo de requisição

​Exemplo de resposta

​Marketing

​Erros

Endpoint

Parâmetros de path

Corpo da requisição

Exemplo de requisição

Exemplo de resposta

Marketing

Erros