# Verificar números

Fonte: https://apiwpp.com/docs/api/contatos/verificar-numeros
Seção: Contatos
Atualizado em: 2026-09-28

`POST /connections/{id}/contacts/check`

Pergunta ao WhatsApp, a partir do número da conexão, se cada telefone da lista tem uma conta no WhatsApp. Verifica até 100 números por requisição e responde um resultado por número, na mesma ordem do pedido. Escopo necessário: `messages:send`.

## Cabeçalhos

| Nome | Obrigatório | Descrição |
| --- | --- | --- |
| `Authorization` | sim | `Bearer <chave de API>`; ou envie a chave em `X-Api-Key`. |
| `Content-Type` | sim | `application/json` |

## Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string · uuid` | sim | Identificador da conexão (o número) que faz a consulta. |

## Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `phones` | `string[]` | sim | Os telefones a verificar, com código do país e DDD (por exemplo, `5511988887777`). Só os dígitos de cada item são lidos, então `+55 (11) 98888-7777` também vale. De 1 a 100 itens. (até 100 itens) |

## Exemplo de requisição

### cURL

```bash
curl -X POST \
  https://api.apiwpp.com/connections/$CONNECTION_ID/contacts/check \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phones": [
      "5511988887777",
      "5511955550000"
    ]
  }'
```

### Node.js

```javascript
const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/contacts/check`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phones: [
      '5511988887777',
      '5511955550000',
    ],
  }),
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->post("https://api.apiwpp.com/connections/{$connectionId}/contacts/check", [
        'phones' => [
            '5511988887777',
            '5511955550000',
        ],
    ]);
```

### Python

```python
import requests

response = requests.post(
    f"https://api.apiwpp.com/connections/{connection_id}/contacts/check",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "phones": [
            "5511988887777",
            "5511955550000",
        ],
    },
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | Um item em `results` por telefone, na ordem do pedido: `phone` (o valor exatamente como foi enviado), `exists` (`true` quando o número tem conta no WhatsApp) e `jid` (o endereço em que a conta está registrada; só vem quando `exists` é `true`). Use esse `jid` como `to` para enviar ao endereço confirmado. |
| 400 | `FST_ERR_VALIDATION` | A requisição não segue o schema: o `id` do caminho não é um UUID, ou falta `phones`, ou ele não é uma lista, ou tem mais de 100 itens. `message` diz o que está errado. |
| 400 |  | `phones` veio vazio (`{"error": "phones array is required"}`), ou a conexão não está `open` (`Connection not ready (status: …)`): o número precisa estar pareado e conectado. |
| 401 |  | Sem chave de API, ou com uma chave inválida: desconhecida, revogada ou expirada. O corpo é `{"error": "Unauthorized"}`. |
| 402 | `subscription_inactive` | A organização não pode usar o WhatsApp agora: o período de teste acabou, ou uma fatura venceu e passou do prazo de carência. Regularize o pagamento no painel para voltar a usar o número. |
| 403 |  | A chave não tem o escopo `messages:send`; a mensagem cita o escopo (`This credential lacks the messages:send scope`). |
| 404 |  | A conexão não existe ou não é de quem chama: o recurso de outra pessoa responde exatamente como um que não existe (`{"error": "Connection not found"}`). |
| 429 |  | Requisições demais deste IP de origem (por padrão, 600 por minuto), ou autenticações com falha demais (por padrão, 20 a cada 5 minutos): espere os segundos de `Retry-After`. Veja [Limites](https://apiwpp.com/docs/referencia/limites). Cabeçalhos: `Retry-After`. |
| 500 |  | O WhatsApp não respondeu a uma das consultas, e a requisição inteira falhou (`Failed to check contacts`). Nada muda: repita depois. |
| 501 | `unsupported_by_provider` | O provedor da conexão não faz esta consulta. O corpo é `{"error": "unsupported_by_provider"}`. |
| 503 |  | A instância do gateway que roda a conexão está mudando (um reinício, um failover) ou não responde: espere os segundos de `Retry-After` e tente de novo. Cabeçalhos: `Retry-After`. |

### 200 OK

```json
{
  "results": [
    {
      "phone": "5511988887777",
      "exists": true,
      "jid": "5511988887777@s.whatsapp.net"
    },
    {
      "phone": "5511955550000",
      "exists": false
    }
  ]
}
```

## Detalhes

Cada número é consultado sozinho (até 10 ao mesmo tempo), porque o WhatsApp responde com o JID em que a conta está registrada, e ele pode não ter os mesmos dígitos que você enviou: uma conta brasileira registrada antes do nono dígito existe como `551188887777@s.whatsapp.net`, não como `5511988887777@s.whatsapp.net`. O gateway nunca põe nem tira o nono dígito por conta própria; `jid` traz o endereço que o WhatsApp respondeu.

É a mesma consulta que `POST /connections/{id}/send` faz antes de enviar para um número: um número que não está no WhatsApp falha na hora, sem novas tentativas. As respostas positivas ficam guardadas por 7 dias e são reaproveitadas pelos envios; as negativas não são guardadas, porque o número pode entrar no WhatsApp depois.

A consulta usa a sessão de WhatsApp do número, como um envio: por isso pede o escopo `messages:send`, a conexão `open` e a organização em dia. Ela não conta na cota de mensagens do plano. Se o WhatsApp não responder a uma das consultas, a requisição inteira falha com `500` (`{"error": "Failed to check contacts"}`); repita depois.

Guia: [Enviar mensagens](https://apiwpp.com/docs/guias/enviar-mensagens).
