A API do WiseData NPS permite que outro sistema — seu CRM, e-commerce ou ERP — leia e mantenha seus contatos e listas de contatos de forma automática, sem ninguém precisar mexer no painel. É uma API REST: você faz requisições HTTP e recebe respostas em JSON. O exemplo deste guia é um CRM que cadastra cada cliente novo na lista "Clientes ativos".
Os tokens ficam em Coleta › Integrações, disponível a partir do plano Pro — o Free e o teste gratuito de 14 dias não incluem API. Só administradores da conta criam e revogam tokens: para os demais membros, a tela não mostra o botão Novo Token nem a lixeira de revogar, e avisa que só administradores criam e revogam tokens. Se a conta voltar para um plano sem API, os tokens deixam de funcionar: a primeira chamada com cada um responde 403 e o token é revogado.
Visão geral
- Base da URL:
https://api.wisedatanps.com(todos os caminhos começam com/api/v1) - Autenticação: token no cabeçalho
Authorization: Bearer SEU_TOKEN - Formato: JSON nas requisições (com
Content-Type: application/json) e nas respostas - O que dá para fazer: listar, criar, consultar, atualizar e excluir contatos; listar, criar, consultar, renomear e excluir listas de contatos
- O que não dá: o token alcança só contatos e listas. Pesquisas, respostas e relatórios não estão na API — uma chamada a eles com token responde
403.
Passo 1 — Crie um token
Em Coleta › Integrações, clique em Novo Token. Preencha o Nome do token (de 3 a 100 caracteres, ex.: "Integração CRM") e, em O que este token pode fazer, marque só o que a integração precisa:
- Ler contatos — consultar contatos e seus dados.
- Criar e alterar contatos — adicionar, editar e remover contatos.
- Ler listas de contatos — consultar as listas existentes.
- Criar e alterar listas — criar, renomear e remover listas.
O formulário já abre com as duas permissões de leitura marcadas, e é preciso deixar pelo menos uma. Ao marcar uma permissão de escrita, a tela avisa que ela altera e remove dados da sua conta. O CRM do exemplo precisa de Ler listas de contatos (para achar a lista) e Criar e alterar contatos (para cadastrar). As permissões não se editam depois: para mudar, crie um token novo e revogue o antigo.
Clique em Criar Token. O token é exibido uma única vez: copie e guarde em local seguro antes de clicar em Entendi, já copiei. Use o valor inteiro, exatamente como aparece — ele começa com um número e uma barra (12|...), e essa parte faz parte do token.
O token vale 365 dias. Na lista, cada token mostra as permissões, os últimos dígitos, Criado por, Criado em, Último uso e Expira em (a data fica destacada quando está perto de vencer). Token vencido responde 401: crie outro e troque na integração antes da data. O administrador vê e revoga os tokens de toda a conta.
Se um token vazar ou deixar de ser usado, revogue-o — qualquer sistema que o utilize perde o acesso na hora. Use um token por integração, para revogar só o que precisar.
Passo 2 — Autentique suas requisições
Envie o token em todas as chamadas, no cabeçalho de autorização:
Authorization: Bearer SEU_TOKEN Content-Type: application/jsonPasso 3 — Sua primeira requisição
Comece listando suas listas de contatos para descobrir o id de cada uma (permissão Ler listas de contatos):
curl https://api.wisedatanps.com/api/v1/contact-lists/all \ -H "Authorization: Bearer SEU_TOKEN"{ "data": [ { "id": 1, "name": "Clientes ativos", "description": null, "contactsCount": 42, "createdAt": "2026-06-05T13:40:00.000000Z", "updatedAt": "2026-06-05T13:40:00.000000Z" } ] }Com o id da lista em mãos, você já pode consultar ou adicionar contatos a ela.
Endpoints de listas
Listar todas as listas
GET /api/v1/contact-lists/all — Ler listas de contatos. Retorna todas as listas, em ordem alfabética e sem paginação.
Listar listas com paginação
GET /api/v1/contact-lists — Ler listas de contatos. Parâmetros opcionais: search (busca no nome), sort (name, created_at, updated_at ou contacts_count), order (asc ou desc), page e per_page (de 1 a 100; padrão 10). Sem sort, vêm as mais recentes primeiro.
Consultar uma lista
GET /api/v1/contact-lists/{listId} — Ler listas de contatos. Retorna a lista em data.
Criar uma lista
POST /api/v1/contact-lists — Criar e alterar listas. Campos: name (obrigatório, de 2 a 100 caracteres, sem repetir o nome de outra lista da conta) e description (opcional, até 500 caracteres). Responde 201 com message e a lista em data.
Atualizar uma lista
PUT /api/v1/contact-lists/{listId} — Criar e alterar listas. Mesmos campos da criação; name é obrigatório também aqui.
Excluir uma lista
DELETE /api/v1/contact-lists/{listId} — Criar e alterar listas. Exclui a lista e os contatos dela. Lista usada por uma pesquisa ativa não é excluída: a resposta é 409, e é preciso pausar a pesquisa antes.
Endpoints de contatos
Listar contatos de uma lista
GET /api/v1/contact-lists/{listId}/contacts — Ler contatos. Retorna os contatos da lista, de forma paginada. Parâmetros opcionais:
search— busca por nome, e-mail ou telefone.sort—name,email,phoneoucreated_at(padrão).order—ascoudesc(padrão).page— número da página.per_page— itens por página, de 1 a 100 (padrão 10).
Os itens vêm em data; meta traz a paginação (entre outros campos, current_page, per_page, total e last_page) e links traz os endereços das páginas. Trecho da resposta:
{ "data": [ { "id": 123, "name": "João Silva", "email": "joao@empresa.com", "phone": "+5511999999999", "emailStatus": "valid", "phoneStatus": "valid", "createdAt": "2026-06-05T13:40:00.000000Z" } ], "meta": { "current_page": 1, "per_page": 10, "total": 42, "last_page": 5 } }Criar um contato
POST /api/v1/contact-lists/{listId}/contacts — Criar e alterar contatos. Cria um contato e o adiciona à lista indicada. Campos do corpo:
name— obrigatório, de 2 a 100 caracteres.email— opcional, precisa ser um e-mail válido. E-mails descartáveis são recusados, e o mesmo e-mail não se repete dentro de uma lista.phone— opcional, de 8 a 20 caracteres. Use o formato internacional, como+5511999999999.
curl -X POST https://api.wisedatanps.com/api/v1/contact-lists/1/contacts \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "João Silva", "email": "joao@empresa.com", "phone": "+5511999999999" }'Em caso de sucesso, a resposta é 201 com o contato criado:
{ "message": "Contato criado com sucesso.", "data": { "id": 123, "name": "João Silva", "email": "joao@empresa.com", "phone": "+5511999999999", "emailStatus": "pending", "phoneStatus": "pending", "createdAt": "2026-06-05T13:40:00.000000Z" } }E-mail e telefone começam com status pending e passam por uma verificação automática logo em seguida. O emailStatus vira valid, invalid, catch_all, disposable ou unknown; o phoneStatus vira valid quando o número tem WhatsApp, ou not_whatsapp. Consulte o contato depois para ver o resultado.
Consultar um contato
GET /api/v1/contacts/{contactId} — Ler contatos. Retorna o contato em data.
Atualizar um contato
PUT /api/v1/contacts/{contactId} — Criar e alterar contatos. Envie só o que muda entre name, email e phone (mesmas regras da criação). Trocar o e-mail ou o telefone volta o status para pending e refaz a verificação. A resposta traz message e o contato atualizado em data.
Excluir um contato
DELETE /api/v1/contacts/{contactId} — Criar e alterar contatos. Remove o contato da lista. A resposta é apenas uma message de confirmação.
Como ler as respostas
Um único recurso vem dentro de data; quando há uma ação (criar, atualizar, excluir), vem também uma message; e as listagens paginadas trazem data, meta e links. Os campos dos recursos vêm em camelCase (emailStatus, createdAt); os parâmetros que você envia são os mostrados acima (per_page, created_at).
Erros comuns
Todo erro vem em JSON com message.
- 401 — token ausente, inválido, revogado ou vencido. Confira o cabeçalho
Authorizatione se o valor foi copiado inteiro. - 402 — a conta está com pagamento pendente ou assinatura bloqueada. A API volta quando a cobrança for regularizada.
- 403 — o token não tem a permissão da chamada (a resposta traz
missing_abilities, por exemplo["contacts:write"]); a chamada é a um recurso fora da API (só contatos e listas); o plano não inclui API (e o token é revogado); ou quem criou o token precisa entrar no painel para aceitar termos atualizados. - 404 — a lista ou o contato informado não existe (ou não é da sua conta).
- 409 — tentativa de excluir uma lista usada por pesquisa ativa.
- 422 — dados inválidos, inclusive e-mail que já está na lista ou nome de lista repetido. O corpo traz
messagee um objetoerrorsindicando cada campo com problema. - 429 — você ultrapassou o limite de requisições; espere os segundos indicados no cabeçalho
Retry-After(veja abaixo).
Limites de uso
- Todas as requisições: até 120 por minuto no Pro, 300 no Business e 600 no Enterprise (ou o que estiver no contrato). O limite é contado por usuário que criou o token, somando todos os tokens dele.
- Criar, atualizar e excluir contatos: além do limite acima, até 30 por minuto.
- Ao atingir um limite, a API responde
429com o cabeçalhoRetry-After, que diz quantos segundos esperar antes de tentar de novo. Use esse valor na sua integração em vez de um intervalo fixo. A mesma resposta trazX-RateLimit-Limit(o limite) eX-RateLimit-Remaining(quantas chamadas ainda restam).
Boas práticas e segurança
- Nunca exponha o token em código que roda no navegador nem em repositórios públicos — use-o apenas a partir do seu servidor.
- Dê ao token só as permissões que a integração usa: um token de leitura entregue a um fornecedor não consegue apagar nada.
- Para cargas grandes, respeite os 30 cadastros por minuto: envie em ritmo constante em vez de disparar tudo de uma vez.
- Anote a data de Expira em e troque o token antes dela.
A própria página de Integrações traz exemplos prontos em cURL, JavaScript e PHP para você copiar e adaptar.
Para onde ir depois
- Contatos e listas — as mesmas listas e contatos, vistos e gerenciados pelo painel.
- Integrando a pesquisa no seu aplicativo — a pesquisa dentro do app, que usa chamadas públicas e não precisa de token.
Resumindo: um administrador cria em Coleta › Integrações um token com só as permissões necessárias, sua integração envia esse token no cabeçalho Authorization e usa os endpoints de listas e contatos, respeitando os limites por minuto e trocando o token antes de ele vencer.