Bulk WhatsApp Checks: Async Jobs, Four States, and the Cost of a Wrong Answer
Short answer: a bulk WhatsApp check is not a loop around a single-number endpoint. Three properties of the job model decide whether your pipeline is cheap or expensive: the check is asynchronous, the answer is four states rather than a boolean, and the cost is deducted when you submit, not when the job finishes. Get any of them wrong and the invoice is what tells you, months later.
This is about the machinery around the check, not the check itself. The per-lookup price is the least interesting number in the system.
The submit call returns a job, not an answer
A batch request is accepted almost immediately and returns no verdicts. The documented shape takes a product slug, a country hint and an array of numbers, and returns a job handle plus a cost line:
POST https://api.zelnum.com/api/v1/detect
X-API-Key: YOUR_API_KEY
{
"product": "waValid",
"country": "US",
"phones": ["+14155550198", "+442071838750"]
}
// 500
{
"mode": "async",
"task_id": "xKj9aP3qLm7v",
"message": "Task queued.",
"summary": { "total": 5000, "cost_deducted": 0.25 }
}
Look at summary. It is populated on a response whose own message reads "Task queued", which means the charge exists before a single number has been checked. At the pricing catalog’s bulk rate of $0.5 USD per 10,000 rows, a 5,000-row example costs 0.25 USD. This is an illustrative cost calculation; use the actual API response for the charged amount.
You are buying the attempt, not the result.
A retried submit is a second charge
Async jobs plus submit-time billing have a consequence that tends to surface in production rather than in review. A retried submit is a second job and a second charge. The documented WhatsApp request carries no idempotency key, which may not be the whole contract but is enough to plan around: assume that anything you send twice, you pay for twice.
The guard has to live on your side. Hash the batch before sending, store that hash next to the task_id the server hands back, and treat a repeated hash as already submitted. Without it you cannot tell a timeout where the server accepted the request from a timeout where it never arrived, and those two cases need opposite responses.
How to read the four processing outcomes
Open all.csv in the result ZIP. In the English export, result_type identifies registration as registered, unregistered, or unknown. The outcome field adds detail for unknown results.
| Result type | Outcome | Action |
|---|---|---|
| registered | valid | Record a confirmed registration. |
| unregistered | invalid | Record the confirmed WhatsApp result. |
| unknown | unknown_processed | Review the inconclusive lookup. |
| unknown | unknown_unprocessed | Consider retrying the unchecked number. |
Filter for explicit registration or non-registration. Preserve unknown outcomes so your application can handle them separately. See the sample result CSV.
Submission limits and job completion
Bulk submissions are limited to 10 requests per minute per API key. A file can contain up to 1,000,000 numbers for one country and be up to 50 MB. Store the task ID and track job progress separately from submission. See the WhatsApp check API for request details.
A quiet check is still a shared service
The check sends nothing visible to the number being looked up, and that is a real guarantee worth having. It is not a statement about how hard you may hit the lookup. An endpoint that is quiet and cheap per call is still a shared service.
Back off with jitter rather than a fixed interval. A thousand clients retrying on the same one-second boundary is a traffic spike you built yourself; the same clients with randomised delays are just traffic.
Store the receipt alongside the verdict
A verdict has a shelf life. A number that reads unknown in March can read registered in June, and a number that was registered can be reassigned by December. A result without a timestamp is an assertion with no expiry.
Four columns make a result auditable: the number in E.164, the state you received, the task_id that produced it, and the UTC time of the lookup. The task_id is the only thing tying a row back to a line on your bill, and without it, reconciling an unexpected invoice means reconstructing what you sent.
That is the same discipline the lower validation layers need. A number that fails a prefix check fails against a dataset with a version, not against the number itself; an invalid result is a claim about your data, and the fix is to record which data.
A minimal batch shape
Put together, the smallest pipeline that survives contact with real lists:
- Normalise to E.164 and drop anything that will not parse before you send it. Paying to check a string that was never a number is the first cost you can avoid.
- Fingerprint the batch, store the fingerprint, submit, and keep the returned
task_idnext to it. - Submit behind a token bucket sized to the documented rate.
- Poll for the result, then store both the result type and processing outcome.
- Review processed unknowns and decide whether to retry unchecked numbers.
- Reconcile charges against stored
task_ids rather than against your send log.
For a one-off check, the WhatsApp number checker runs the lookup server-side and returns the state alongside the line type. For lists, the bulk WhatsApp checker takes CSV and TXT uploads, and the WhatsApp API reference documents the detect, file and task-result endpoints, the rate, and the activity fields if campaign filtering needs it.
FAQ
Is there a single-number endpoint, or is everything a batch?
Use the realtime endpoint for a single number or the bulk endpoint for a file. The bulk endpoint returns a task ID so you can download the result when it is ready.
What does "unknown" actually mean?
An unknown result is inconclusive. Read outcome to distinguish a lookup that ran from a row that was never checked.
How long does a one-million-number job take?
Completion time varies by job and processing load. Track the task status after submitting a file.
Do I need a WhatsApp Business account to run these checks?
No. This is a verification and list-hygiene API, separate from the messaging API. WhatsApp Business API is for sending approved messages; a check answers whether a number is registered and sends nothing to it.
How do I avoid paying twice for the same list?
Fingerprint the batch before sending and store the fingerprint with the returned task_id. If a submit times out you cannot tell whether the server accepted it, so the stored fingerprint is what stops a retry from becoming a second job and a second charge.
Which files are in the bulk result ZIP?
The ZIP contains all.csv and a TXT list for each result category present. The outcome column preserves the distinction between processed and unprocessed unknown rows.
Related
Julian works on verification API integrations, batch jobs, CSV workflows, task polling, retry handling, result exports, and developer documentation. His guides explain how teams can integrate verification APIs safely and connect results with internal data systems.
View full author profile →