Referência

WA Lookup Referência da API

Todos os endpoints compartilham uma chave de API e um saldo.

Item	Valor
URL base	https://walookup.com
Cabeçalho de autenticação	X-API-Key: sk_your_api_key
Envelope da resposta	{ code, msg, data }

Os preços não são listados aqui; todos os produtos são cobrados por verificação bem-sucedida. Ver preços

Autenticação

Use uma chave de API criada em Configurações e envie-a em todas as solicitações no cabeçalho X-API-Key.

Cabeçalho de autenticação

X-API-Key: sk_your_api_key

Mantenha sua chave de API em segredoSempre chame este endpoint a partir do seu servidor. Qualquer pessoa que tenha a chave pode gastar seu saldo.

Verificações síncronas

POST/api/v1/checkPOST/api/v1/batch-check

Envie um identificador, ou até 100 em uma única solicitação, e leia o resultado na mesma resposta. Sem polling, sem callbacks. Um resultado indeterminado retorna 422 com code 42200 e não é cobrado. Uma solicitação múltipla mantém a ordem de entrada, cobra cada identificador de forma independente e tem 300 segundos para terminar — se não terminar, a solicitação inteira falha e todas as cobranças são reembolsadas.

Parâmetros

Campo	Tipo	Descrição
`service_type`	string	Código do produto, um dos produtos listados abaixo.
`identifier`	string	Verificação única: um número de telefone no formato E.164, com ou sem o `+` inicial. O servidor o normaliza.
`identifiers`	string[]	Verificação múltipla: de 1 a 100 números de telefone. A resposta preserva esta ordem.

Produtos deste grupo

Verificação de registro no WhatsAppwsConfirme se um número está registrado no WhatsApp — útil para verificar uma lista de contatos antes de enviar.Página do produto
Verificação de foto de perfil do WhatsAppws_avatarVerifique se um número está registrado no WhatsApp e retorne os campos de foto de perfil: avatar (se uma foto foi obtida) e avatar_url.Página do produto
Verificação de conta WhatsApp Businessws_businessVerifique o registro e identifique se o número usa uma conta WhatsApp Business.Página do produto

Verificação de registro no WhatsApp

wstelefone

Confirme se um número está registrado no WhatsApp — útil para verificar uma lista de contatos antes de enviar.

Verificação única

POST/api/v1/check

Solicitação

curl -X POST "https://walookup.com/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws", "identifier": "+17253100591" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws",
    "identifier": "+17253100591",
    "registered": true
  }
}

Campos da resposta

Campo	Tipo	Descrição
`registered`	boolean	Se o número está registrado no WhatsApp.

Verificação múltipla

POST/api/v1/batch-check

Solicitação

curl -X POST "https://walookup.com/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws", "identifiers": ["+17253100591", "+14155550000", "12345"] }'

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "registered": true
      },
      {
        "identifier": "+14155550000",
        "exists": true,
        "registered": false
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Campos da resposta

Campo	Tipo	Descrição
`exists`	boolean	Se este número gerou um resultado. false significa que o formato era inválido, o resultado foi indeterminado ou a verificação falhou; quando false, nenhum dos campos abaixo está presente.
`registered`	boolean	Se o número está registrado (`registered`). Presente apenas quando `exists` é true, com o mesmo significado da verificação única.

Verificação de foto de perfil do WhatsApp

ws_avatartelefone

Verifique se um número está registrado no WhatsApp e retorne os campos de foto de perfil: avatar (se uma foto foi obtida) e avatar_url.

Verificação única

POST/api/v1/check

Solicitação

curl -X POST "https://walookup.com/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws_avatar", "identifier": "+17253100591" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_avatar",
    "identifier": "+17253100591",
    "registered": true,
    "avatar": true,
    "avatar_url": "<image url>"
  }
}

Campos da resposta

Campo	Tipo	Descrição
`registered`	boolean	Se o número está registrado no WhatsApp.
`avatar`	boolean	Se a conta tem uma foto de perfil definida. avatar_url ainda pode estar vazio quando a imagem não está disponível.
`avatar_url`	string	A URL da foto de perfil; uma string vazia quando nenhuma URL está disponível.

Verificação múltipla

POST/api/v1/batch-check

Solicitação

curl -X POST "https://walookup.com/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws_avatar", "identifiers": ["+17253100591", "+14155550000", "12345"] }'

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_avatar",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "registered": true,
        "avatar": true,
        "avatar_url": "<image url>"
      },
      {
        "identifier": "+14155550000",
        "exists": true,
        "registered": false,
        "avatar": false,
        "avatar_url": ""
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Campos da resposta

Campo	Tipo	Descrição
`exists`	boolean	Se este número gerou um resultado. false significa que o formato era inválido, o resultado foi indeterminado ou a verificação falhou; quando false, nenhum dos campos abaixo está presente.
`registered`	boolean	Se o número está registrado (`registered`). Presente apenas quando `exists` é true, com o mesmo significado da verificação única.
`avatar`	boolean	Se a conta tem uma foto de perfil definida. avatar_url ainda pode estar vazio quando a imagem não está disponível.
`avatar_url`	string	A URL da foto de perfil; uma string vazia quando nenhuma URL está disponível.

Verificação de conta WhatsApp Business

ws_businesstelefone

Verifique o registro e identifique se o número usa uma conta WhatsApp Business.

Verificação única

POST/api/v1/check

Solicitação

curl -X POST "https://walookup.com/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws_business", "identifier": "+17253100591" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_business",
    "identifier": "+17253100591",
    "registered": true,
    "business": true
  }
}

Campos da resposta

Campo	Tipo	Descrição
`registered`	boolean	Se o número está registrado no WhatsApp.
`business`	boolean	Se a conta é uma conta WhatsApp Business.

Verificação múltipla

POST/api/v1/batch-check

Solicitação

curl -X POST "https://walookup.com/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws_business", "identifiers": ["+17253100591", "+14155550000", "12345"] }'

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_business",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "registered": true,
        "business": true
      },
      {
        "identifier": "+14155550000",
        "exists": true,
        "registered": false,
        "business": false
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Campos da resposta

Campo	Tipo	Descrição
`exists`	boolean	Se este número gerou um resultado. false significa que o formato era inválido, o resultado foi indeterminado ou a verificação falhou; quando false, nenhum dos campos abaixo está presente.
`registered`	boolean	Se o número está registrado (`registered`). Presente apenas quando `exists` é true, com o mesmo significado da verificação única.
`business`	boolean	Se a conta é uma conta WhatsApp Business.

Verificações assíncronas

POST/api/v1/bulk-tasksGET/api/v1/bulk-tasks/{id}

Envie um arquivo e receba um ID de tarefa imediatamente; depois, consulte esse ID até que seja concluído com sucesso. A resposta de sucesso inclui result_url, o link para baixar o resultado. Existem apenas duas ações: enviar e consultar. Não consulte com frequência maior que uma vez a cada 30 segundos.

Parâmetros

Campo	Tipo	Descrição
`service_type`	string	Código do produto em massa, um dos produtos listados abaixo.
`country`	string	Código ISO 3166-1, como `US`. Obrigatório para tarefas de números: cada número deve incluir o código do país e pertencer a este país (os números que não atendem a isso são excluídos e não são cobrados); também define o roteamento. Em multipart, deve vir antes de `file`.
`file`	file	Um `.txt` ou `.csv` com um identificador por linha, até `max_file_bytes` (20MB por padrão).
`Idempotency-Key`	header	Opcional, até 128 caracteres. Reenviar a mesma chave retorna a tarefa original em vez de criar uma segunda.

Produtos deste grupo

Verificação de registro em massa do WhatsAppws_batchEnvie um arquivo inteiro de números, descubra quais estão registrados no WhatsApp e baixe o arquivo de resultado quando terminar.Página do produto
Verificação de foto de perfil em massa do WhatsAppws_avatar_batchVerifique uma lista inteira quanto ao registro no WhatsApp e à foto de perfil: se cada número registrado tem uma foto definida, além da URL da foto.Página do produto
Verificação Business em massa do WhatsAppws_business_batchVerifique uma lista inteira em busca de contas WhatsApp Business: se cada número está no WhatsApp e se essa conta é uma conta WhatsApp Business.Página do produto
Verificação de atividade em massa do WhatsAppws_active_batchStatus de registro mais dias de atividade — dias desde a última atividade do número — para distinguir números ativos de inativos em uma lista inteira.Página do produto

Verificação de registro em massa do WhatsApp

ws_batchtelefone1.000–500.000 por tarefa

Envie um arquivo inteiro de números, descubra quais estão registrados no WhatsApp e baixe o arquivo de resultado quando terminar.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

curl -X POST "https://walookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=ws_batch \
  -F country=US \
  -F file=@numbers.txt

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Consultar a tarefa

GET/api/v1/bulk-tasks/{id}

Solicitação

curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	17253100591	O número enviado apenas em dígitos, com o código do país, sem sinal de mais nem espaços (ex.: 17253100591).
`activated`	true	Se o número está registrado no WhatsApp: true ou false.

Verificação de foto de perfil em massa do WhatsApp

ws_avatar_batchtelefone1.000–500.000 por tarefa

Verifique uma lista inteira quanto ao registro no WhatsApp e à foto de perfil: se cada número registrado tem uma foto definida, além da URL da foto.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

curl -X POST "https://walookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=ws_avatar_batch \
  -F country=US \
  -F file=@numbers.txt

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_avatar_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Consultar a tarefa

GET/api/v1/bulk-tasks/{id}

Solicitação

curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_avatar_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	17253100591	O número enviado apenas em dígitos, com o código do país, sem sinal de mais nem espaços (ex.: 17253100591).
`activated`	true	Se o número está registrado no WhatsApp: true ou false. Quando não é true, todas as outras colunas dessa linha ficam vazias.
`avatar`	true	Se a conta tem uma foto de perfil definida: true ou false. avatar_url ainda pode estar vazio quando a imagem não está disponível.
`avatar_url`	https://pps.whatsapp.net/v/example.jpg	A URL da foto de perfil; vazia quando nenhuma URL está disponível.

Verificação Business em massa do WhatsApp

ws_business_batchtelefone1.000–500.000 por tarefa

Verifique uma lista inteira em busca de contas WhatsApp Business: se cada número está no WhatsApp e se essa conta é uma conta WhatsApp Business.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

curl -X POST "https://walookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=ws_business_batch \
  -F country=US \
  -F file=@numbers.txt

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_business_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Consultar a tarefa

GET/api/v1/bulk-tasks/{id}

Solicitação

curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_business_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	17253100591	O número enviado apenas em dígitos, com o código do país, sem sinal de mais nem espaços (ex.: 17253100591).
`activated`	true	Se o número está registrado no WhatsApp: true ou false. Quando não é true, todas as outras colunas dessa linha ficam vazias.
`business`	false	Se a conta é uma conta WhatsApp Business: true ou false.

Verificação de atividade em massa do WhatsApp

ws_active_batchtelefone1.000–500.000 por tarefa

Status de registro mais dias de atividade — dias desde a última atividade do número — para distinguir números ativos de inativos em uma lista inteira.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

curl -X POST "https://walookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=ws_active_batch \
  -F country=US \
  -F file=@numbers.txt

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_active_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Consultar a tarefa

GET/api/v1/bulk-tasks/{id}

Solicitação

curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_active_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	17253100591	O número enviado apenas em dígitos, com o código do país, sem sinal de mais nem espaços (ex.: 17253100591).
`activated`	true	Se o número está registrado no WhatsApp: true ou false. Quando não é true, todas as outras colunas dessa linha ficam vazias.
`activedays`	9	Dias desde a última atividade do número — quanto menor, mais recente.

Saldo

GET/api/v1/balance

Lê o saldo atual da conta em micros de USD. Somente leitura: não cria registro de verificação nem cobra nada.

Saldo

GET/api/v1/balance

Solicitação

curl "https://walookup.com/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

Concorrência, tempos limite e comportamento de novas tentativas

As verificações são síncronas. Use o code retornado para decidir se aceita o resultado ou tenta novamente.

Campo	Descrição
`5 solicitações simultâneas por usuário`	As verificações únicas e múltiplas compartilham este limite, e uma solicitação múltipla conta como uma solicitação, independentemente de quantos números ela contenha. Além disso, apenas uma verificação múltipla por conta é executada por vez; uma segunda é rejeitada até que a primeira termine. Atingir qualquer um dos limites retorna `code` `42901` imediatamente, sem cobrança, com um cabeçalho `Retry-After` — reenvie assim que uma solicitação em andamento terminar.
`60s para única, 300s para múltipla`	Exceder o tempo limite retorna `code` `50400`, sem cobrança. Uma verificação múltipla que excede o tempo falha por completo — sem resultados parciais, e o valor total é reembolsado.
`Uma verificação múltipla aceita até 100 números`	Os resultados preservam a ordem e a quantidade do envio. Uma verificação múltipla por conta é executada por vez; envie o próximo lote depois que o anterior retornar.

Códigos de erro

Código	Descrição
`40000`	Tipo de serviço não suportado ou campos da solicitação conflitantes
`40001`	Corpo JSON inválido
`40002`	Número inválido
`40100`	Chave de API ausente ou inválida
`40200`	Saldo insuficiente
`42200`	Não foi possível determinar o número neste momento. Nenhum `data` é retornado e a solicitação não é cobrada
`42900`	Uma cota de uso foi esgotada ou há pedidos não concluídos demais
`42901`	Todas as cinco vagas de solicitações simultâneas estão ocupadas ou já há uma verificação múltipla em execução nesta conta; envie depois que uma solicitação em andamento terminar. A solicitação rejeitada não é cobrada e inclui um cabeçalho `Retry-After`
`50303`	O serviço está no limite da capacidade agora; sem cobrança. Aguarde os segundos de `Retry-After` e reenvie a mesma solicitação
`50400`	A verificação não terminou dentro do tempo limite e não é cobrada; tente novamente. O tempo esgotado de um lote faz o lote inteiro falhar e reembolsa o valor total
`50300`	Manutenção do serviço de validação