WA Lookup

API contract

Two steps: submit the file, then check the task

Read the full API docs Open API Keys

Submitting returns a task id right away; check the task by that id and, once it succeeds, the response carries the result file download link. Each request is shown with its own response.

1. Submit the file

The task id comes back straight away with preparing set to true while the file is prepared in the background: invalid lines, duplicates and — for number tasks — numbers without a country code or from another country are removed and not charged. Balance is reserved for the submitted lines and settled on completion; the difference is refunded.

cURL requestPOST /api/v1/bulk-tasks
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
Response: task created200 OK
{
  "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"
  }
}

2. Check the task

Poll by task id. Once preparation finishes, submitted_lines = total + invalid_cnt + no_code_cnt + other_country_cnt + duplicate_cnt, where total is what is checked and charged. A successful response carries the success and failure counts and the result file download link; a task refused during preparation is failed with reason_detail and refunded in full.

cURL requestGET /api/v1/bulk-tasks/{id}
curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
Response: task finished200 OK
{
  "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"
  }
}

How it runs

What happens to a bulk task

Bulk is not realtime made bigger — it is submit once, run in the background, collect later. You do not need to keep the page open; task state and results stay in your dashboard.

  1. 01Upload the file

    A .txt or .csv with one number per line. It is streamed straight through; nothing is written to disk.

  2. 02Precheck and reserve

    Obvious problems (an empty file, the wrong format, too few lines) are rejected on upload. Balance is then reserved and the file is prepared in the background: invalid lines, duplicates and numbers without a country code or from another country are removed, and the single-country rule is checked. A file that fails there ends as a failed task, refunded in full; otherwise only the remaining lines are checked, and the task is settled on completion.

  3. 03Run in the background

    The task runs on its own — close the page if you like. A failure is reported straight away and fully refunded.

  4. 04Download the result

    Collect the file from the bulk check page. You pay only for numbers that actually returned a result; the difference is refunded.

When bulk fits

When bulk is worth it — and when realtime is faster

Realtime checkBulk check
How many numbers1 number per single check; several per multi request — exact caps are in the API docsA whole large list in one task — the current size range is on the pricing page
Getting resultsRight away: single and multi-endpoint answer in the same response; the dashboard returns them one by oneDownload a result file when the task finishes
Country / regionNo restriction — mix freely in one requestPick one country/region on submission; the list should be essentially that country, and too many numbers from elsewhere fail the task with a full refund
Result shapeJSON, fields per numberResult file (one CSV with the full table)
Typical useForm validation, agent lookups, pre-send gatingList hygiene, pre-campaign filtering, stored-data cleanup

Realtime check · View pricing

Product FAQ

About Avatar check

When should I use bulk instead of a realtime check?

Use bulk for a whole large list. For a handful of numbers the realtime check answers in the same request, with no task to schedule.

What happens to invalid numbers in the file?

The precheck drops malformed lines, so they never enter the billable count. Of the numbers that remain, any the upstream cannot resolve are not charged either. You pay only for numbers that actually return a result.

How long does a task take?

It depends on the number count and the product. You can close the page after submitting; the task runs in the background and the result waits for you on the bulk check page.

Do I get refunded if it fails?

Yes. A failed task is refunded in full. If the task succeeds but some numbers return nothing, that portion is refunded automatically. The difference between the reserved amount and what was actually charged always comes back.

Related products

Other bulk products

WhatsApp Bulk Registration CheckUpload a whole file of numbers, find out which ones are registered on WhatsApp, and download the result file when it finishes.WhatsApp Bulk Business CheckCheck a whole list for WhatsApp Business accounts: whether each number is on WhatsApp, and whether that account is a WhatsApp Business account.WhatsApp Bulk Activity CheckRegistration status plus active days — days since the number was last active — so you can tell live numbers from dormant ones across a whole list.