> ## 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.

# Verify WhatsApp numbers

> Check whether one or more numbers are on WhatsApp, then import matched numbers as contacts.

## Endpoints

| Method | Endpoint                                      |
| ------ | --------------------------------------------- |
| `POST` | `/api/v1/number-lookups`                      |
| `GET`  | `/api/v1/number-lookups`                      |
| `GET`  | `/api/v1/number-lookups/{id}`                 |
| `GET`  | `/api/v1/number-lookups/{id}/progress`        |
| `POST` | `/api/v1/number-lookups/{id}/cancel`          |
| `POST` | `/api/v1/number-lookups/{id}/import-contacts` |

## Rules

* `instanceId` est obligatoire
* moins de `100` numéros : traitement synchrone
* `100` numéros ou plus : traitement asynchrone
* les numéros valides sont traités par batchs provider de `20`
* seuls les numéros trouvés sur WhatsApp peuvent être importés en contacts

## Lancer une vérification

```bash theme={null}
curl -X POST https://srv.msgflash.com/api/v1/number-lookups \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "INSTANCE_UUID",
    "numbers": ["+41791234567", "+81476222311"]
  }'
```

## Response synchrone

```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": []
    }
  }
}
```

## Response asynchrone

```json theme={null}
{
  "data": {
    "mode": "async",
    "lookupId": "lookup_uuid",
    "status": "pending",
    "requested": 1250,
    "message": "Lookup in progress. Check status later."
  }
}
```

## Read status

```bash theme={null}
curl https://srv.msgflash.com/api/v1/number-lookups/LOOKUP_ID \
  -H "x-api-key: msgf_live_your_api_key_here"
```

## Track progress

```bash theme={null}
curl https://srv.msgflash.com/api/v1/number-lookups/LOOKUP_ID/progress \
  -H "x-api-key: msgf_live_your_api_key_here"
```

## Cancel an async lookup

```bash theme={null}
curl -X POST https://srv.msgflash.com/api/v1/number-lookups/LOOKUP_ID/cancel \
  -H "x-api-key: msgf_live_your_api_key_here"
```

## Importer les numéros trouvés comme contacts

```bash theme={null}
curl -X POST https://srv.msgflash.com/api/v1/number-lookups/LOOKUP_ID/import-contacts \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "verified-whatsapp"
  }'
```

<Note>
  Lookup always depends on a connected instance in your account.
</Note>