Verification methodology
How WA Lookup verifies a WhatsApp number
WA Lookup accepts one E.164 phone number, applies the selected service type, and returns a synchronous result. This reference explains the complete request lifecycle, what each state means, when balance is charged, and where the result should not be over-interpreted.
Reviewed July 21, 2026
What happens during a WhatsApp check?
A check validates the request, reserves the selected product cost, sends one normalized number through the verification service, and returns the result in the same HTTP response. A completed result keeps the charge. A failed, timed-out, or undetermined request returns the reserved balance and must not be classified as registered or unregistered.
The request lifecycle from input to result
The dashboard and REST API use the same core verification flow, so the meaning of the response does not change between manual and automated checks.
- 1
Normalize the identifier
Submit one phone number in E.164 form, including the country code. Invalid or conflicting fields are rejected before a verification attempt.
- 2
Select the required service type
Use ws for registration, ws_avatar for registration plus avatar availability, or ws_business for registration plus the Business account field.
- 3
Reserve balance and run the check
The selected product cost is reserved before the synchronous verification request. A rate or concurrency rejection does not create a completed check.
- 4
Commit or refund the charge
A usable result keeps the charge and is saved to history. A failed or undetermined attempt returns the balance and records zero final charge.
Result states are separate from HTTP success
Always classify the business result from the response envelope and data fields together. A network or service error is not evidence about the submitted number.
| State | Meaning | Recommended action |
|---|---|---|
| Completed · registered=true | The check reported that the number was registered on WhatsApp at request time. | Store the timestamp and selected service type with the result. |
| Completed · registered=false | The check reported that the number was not registered at request time. | Keep it distinct from invalid input and temporary failures. |
| Undetermined or service error | No usable registration decision was produced. | Keep the record pending or retry later; do not write false. |
| 429 | The user rate or concurrency limit was reached. | Back off, queue excess work, and retry after the limit window. |
| 503 | The verification service is temporarily unavailable. | Retry later and preserve the previous known state, if any. |
What each product adds
Choose the least expensive service type that answers the current question. Additional fields do not make the registration result more authoritative.
- ws answers registration status and is the right default for list hygiene.
- ws_avatar adds avatar availability and an avatar URL when the field is available; absence does not mean unregistered.
- ws_business adds the Business account flag; a false value does not describe company legitimacy or ownership.
- All fields describe the response at one point in time and can change later.
Operational and consent boundaries
Verification is a data-quality signal, not permission or identity proof. Keep the result, request time, product code, and processing outcome together so later systems can distinguish a completed decision from a retryable failure.
- Do not infer name, identity, ownership, activity, last seen, or message history.
- Do not treat a registered result as consent to contact the person.
- Re-check when a workflow needs a current status rather than assuming an old result remains valid.
- Protect phone numbers, API keys, and exported validation history according to your own access and retention policies.