# Validate numbers

> Docs index: https://wahasend.com/llms.txt · Everything in one file: https://wahasend.com/docs.md · API base URL: https://app.wahasend.com/api/v1

Find out which numbers are on WhatsApp before you write to them. Comes with **Notify**, **Developer** and **Connect** (feature `batch`). Nothing is sent.

<a id="alert-validate"></a>

### Check up to 500 numbers

`POST /api/v1/alert/validate`

Returns the numbers that are on WhatsApp and those that aren't, as digits. `@lid` ids count as valid.

- Unlocked by: Notify, Developer, Connect (`batch`)
- Per-number key: yes

> When **none** of the numbers is on WhatsApp the answer is a 400 `NO_VALID_NUMBERS` error with `details.invalidNumbers`, not an empty `valid` list.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phones` | string[] | yes | 1–500 phone numbers or `@lid` ids. |
| `containerId` | uuid | no | Which of your WhatsApp numbers to use; it always wins. Default: your default number (else any connected one), or a number of the group when [several numbers](https://wahasend.com/docs/phone-numbers.md#several-numbers) is on. Ignored with a per-number key, which always uses its own number. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/alert/validate \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phones": [
    "+22212345678",
    "+22287654321"
  ]
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/alert/validate', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "phones": [
      "+22212345678",
      "+22287654321"
    ]
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/alert/validate",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "phones": [
            "+22212345678",
            "+22287654321",
        ],
    },
)
print(r.json())
```

**Response 200**

```json
{
  "success": true,
  "valid": [
    "22212345678"
  ],
  "invalid": [
    "22287654321"
  ],
  "total": 2
}
```

**Errors to expect**

- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NO_VALID_NUMBERS`](https://wahasend.com/docs/errors.md#no_valid_numbers) (400): None of these numbers are on WhatsApp.
- [`NUMBER_VALIDATION_UNAVAILABLE`](https://wahasend.com/docs/errors.md#number_validation_unavailable) (503): Numbers cannot be checked right now. Try again shortly.
- [`NO_SESSION_CONFIGURED`](https://wahasend.com/docs/errors.md#no_session_configured) (400): This account has no connected WhatsApp number.

<a id="recipients-validate"></a>

### Check a long list (up to 10,000)

`POST /api/v1/recipients/validate`

For contact lists: removes duplicates, checks the format, then asks WhatsApp five numbers at a time. Slower; use it before a campaign.

- Unlocked by: Notify, Developer, Connect (`batch`)
- Per-number key: yes

> A number WhatsApp could not be asked about is listed as valid with an empty `chatId`.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phones` | string[] | yes | 1–10,000 phone numbers. Spaces, dashes and brackets are removed. |
| `containerId` | uuid | no | Which of your WhatsApp numbers to use; it always wins. Default: your default number (else any connected one), or a number of the group when [several numbers](https://wahasend.com/docs/phone-numbers.md#several-numbers) is on. Ignored with a per-number key, which always uses its own number. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/recipients/validate \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phones": [
    "+222 12 34 56 78",
    "+22287654321",
    "12"
  ]
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/recipients/validate', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "phones": [
      "+222 12 34 56 78",
      "+22287654321",
      "12"
    ]
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/recipients/validate",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "phones": [
            "+222 12 34 56 78",
            "+22287654321",
            "12",
        ],
    },
)
print(r.json())
```

**Response 200**

```json
{
  "success": true,
  "total": 3,
  "valid": 1,
  "invalid": 2,
  "validNumbers": [
    {
      "phone": "+22212345678",
      "chatId": "22212345678@c.us"
    }
  ],
  "invalidNumbers": [
    {
      "phone": "12",
      "reason": "Invalid format",
      "code": "invalid_format"
    },
    {
      "phone": "+22287654321",
      "reason": "Not on WhatsApp",
      "code": "not_on_whatsapp"
    }
  ]
}
```

**Errors to expect**

- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NO_SESSION_CONFIGURED`](https://wahasend.com/docs/errors.md#no_session_configured) (400): This account has no connected WhatsApp number.