> ## Documentation Index
> Fetch the complete documentation index at: https://docs.msgflash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST Create a number lookup

> Check one or more WhatsApp numbers synchronously or asynchronously depending on volume.

## Endpoint

```txt theme={null}
POST /api/v1/number-lookups
```

## Body

| Field        | Type      | Required | Description                                |
| ------------ | --------- | -------: | ------------------------------------------ |
| `instanceId` | UUID      |      yes | ID de l’instance connectée à utiliser      |
| `numbers`    | string\[] |      yes | 1 à 10 000 numéros au format international |

## Processing rules

* moins de `100` numéros : réponse synchrone
* `100` numéros ou plus : réponse asynchrone `202`
* les numéros valides sont traités côté provider par batchs de `20`

## Success response `200` ou `202`

```json theme={null}
{
  "data": {
    "mode": "sync",
    "lookupId": "lookup_uuid",
    "status": "done",
    "requested": 2,
    "normalized": 2,
    "checked": 2,
    "onWhatsAppCount": 1,
    "notOnWhatsAppCount": 1,
    "invalidCount": 0,
    "result": {
      "onWhatsApp": [],
      "notOnWhatsApp": [],
      "invalid": []
    }
  }
}
```

## Common errors

| Code               | HTTP | When                        |
| ------------------ | ---- | --------------------------- |
| `VALIDATION_ERROR` | 400  | Invalid body                |
| `NOT_FOUND`        | 404  | Instance not found          |
| `PROVIDER_ERROR`   | 502  | Verification provider error |