Listar contatos

Endpoint

GET /v1/contacts

Escopo necessário: read:contacts

Parâmetros de query

Parâmetro	Tipo	Descrição
`limit`	integer	Itens por página. Padrão: `25`. Máximo: `100`
`cursor`	string	Token de paginação para a próxima página
`sort`	string	Campo de ordenação: `created_at` (padrão), `updated_at`, `name`
`order`	string	Direção: `desc` (padrão) ou `asc`
`search`	string	Busca por nome, email ou telefone (case-insensitive)
`tag`	string	Filtra por tag exata
`source`	string	Fonte do contato (ex: `whatsapp`, `instagram`, `manual`, `api`)
`has_whatsapp`	boolean	`true` / `false` — filtra por presença de WhatsApp
`has_instagram`	boolean	`true` / `false` — filtra por presença de Instagram
`has_messenger`	boolean	`true` / `false` — filtra por presença de Messenger
`created_after`	string	ISO 8601 — contatos criados após esta data
`created_before`	string	ISO 8601 — contatos criados antes desta data
`updated_after`	string	ISO 8601 — contatos atualizados após esta data
`phone`	string	Telefone em qualquer grafia (`+5514999990000`, `14999990000`, `(14) 99999-0000`). Casa também a identidade de WhatsApp
`email`	string	E-mail exato (sem distinção de maiúsculas)
`external_id`	string	Identificador do contato no seu sistema

Exemplo de requisição

curl "https://api.socialsell.ai/v1/contacts?limit=10&tag=vip&has_whatsapp=true" \
  -H "Authorization: Bearer sk_live_..."

Exemplo de resposta

{
  "data": [
    {
      "id": "664f1a2b3c4d5e6f78901234",
      "name": "João Silva",
      "email": "joao@empresa.com.br",
      "phone": "+5511999999999",
      "instagram_username": "joaosilva",
      "whatsapp_jid": "5511999999999@s.whatsapp.net",
      "messenger_psid": null,
      "messenger_name": null,
      "source": "whatsapp",
      "external_id": null,
      "avatar_url": "https://...",
      "company": {
        "id": "664b1c2d3e4f5a6789012346",
        "name": "Empresa ABC"
      },
      "tags": ["vip", "cliente"],
      "custom_fields": {
        "cpf": "123.456.789-00"
      },
      "funnel_stage": "Qualificados",
      "marketing": {
        "status": "consented",
        "consent": { "given": true, "given_at": "2026-05-02T11:00:00.000Z", "method": "form", "source": "Formulário do site /contato" },
        "opt_out": { "at": null, "source": null, "reason": null }
      },
      "notes_count": 3,
      "deals_count": 2,
      "last_message_at": "2026-06-01T14:22:00.000Z",
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-06-01T14:22:00.000Z"
    }
  ],
  "meta": {
    "total": 350,
    "has_more": true,
    "next_cursor": "eyJpZCI6IjY2NGYxYTJiM2M0ZDVlNmY3ODkwMTIzNCIsImNhIjoiMjAyNi0wMS0xNVQxMDozMDowMC4wMDBaIn0",
    "request_id": "req_a1b2c3d4e5f6a7b8"
  }
}

Objeto contato

Campo	Tipo	Descrição
`id`	string	ID único do contato
`name`	string	Nome completo
`email`	string\|null	Email
`phone`	string\|null	Telefone
`instagram_username`	string\|null	Username do Instagram
`whatsapp_jid`	string\|null	JID do WhatsApp (ex: `5511999999999@s.whatsapp.net`)
`messenger_psid`	string\|null	PSID do Facebook Messenger
`messenger_name`	string\|null	Nome no Messenger
`source`	string\|null	Origem: `whatsapp`, `instagram`, `messenger`, `manual`, `import`, `api`
`external_id`	string\|null	Identificador do contato no seu sistema, único por organização
`avatar_url`	string\|null	URL do avatar
`company`	object\|null	Empresa vinculada `{id, name}`
`tags`	string[]	Lista de tags
`custom_fields`	object	Campos personalizados (chave → valor)
`funnel_stage`	string\|null	Etapa no funil de contatos
`marketing`	object	Autorização e descadastro de mensagens de marketing. Veja abaixo
`notes_count`	integer	Quantidade de notas
`deals_count`	integer	Quantidade de negócios vinculados ao contato
`last_message_at`	string\|null	Timestamp da última mensagem
`created_at`	string	Timestamp de criação (ISO 8601)
`updated_at`	string	Timestamp de atualização (ISO 8601)

`marketing`

Duas informações independentes sobre mensagens promocionais:

Autorização (consent) é a prova de que a pessoa aceitou receber promoções, coletada fora da SocialSell — por exemplo, o formulário do seu site. Serve como filtro opcional nos disparos.
Descadastro (opt_out) é o pedido para parar. É absoluto: o contato descadastrado fica fora de todo envio promocional, mesmo com autorização registrada. Mensagens de atendimento continuam normais.

Campo	Tipo	Descrição
`marketing.status`	string	`opted_out` quando há descadastro; senão `consented` quando há autorização; senão `none`
`marketing.consent.given`	boolean	Se há autorização registrada
`marketing.consent.given_at`	string\|null	Quando a autorização foi registrada
`marketing.consent.method`	string\|null	Como foi coletada: `form` (formulário), `manual` (cadastro pela equipe), `reply` (pedido na conversa), `import` (planilha)
`marketing.consent.source`	string\|null	Onde foi coletada, em texto livre (ex.: `Formulário do site /contato`)
`marketing.opt_out.at`	string\|null	Quando o contato pediu para não receber promoções. `null` = sem descadastro
`marketing.opt_out.source`	string\|null	Origem do pedido: `meta_preference` (desligou as promoções no próprio WhatsApp), `meta_error_131050` (a Meta recusou um envio por esse motivo), `keyword` (respondeu uma palavra como SAIR), `manual` (equipe), `api` (integração)
`marketing.opt_out.reason`	string\|null	Motivo informado, quando houver

Para registrar autorização ou descadastro, use marketing_consent e marketing_opt_out em Criar contato ou Atualizar contato.

Não existe filtro por responsável nesta listagem. Contato não tem responsável na v1 — a atribuição acontece por conversa. Para achar as conversas de um atendente, use GET /v1/conversations?assigned_to=....

Erros

Além dos erros comuns a toda a API — autenticação, escopo e limite de requisições — esta rota pode responder:

Código	Status	Descrição
`INTERNAL_ERROR`	`500`	Falha interna ao processar a requisição

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 query

Exemplo de requisição

Exemplo de resposta

Objeto contato

`marketing`

Erros

​Endpoint

​Parâmetros de query

​Exemplo de requisição

​Exemplo de resposta

​Objeto contato

​marketing

​Erros

Endpoint

Parâmetros de query

Exemplo de requisição

Exemplo de resposta

Objeto contato

`marketing`

Erros