WA Lookup
A phone number moving through a synchronous registration-check pipeline to a completed result
One request carries one normalized number through validation and returns one registration result.

What “real time” means for this product

Real time means the registration decision is returned in the same HTTP request rather than through a background job, webhook, or later export.

The caller sends one normalized phone number and waits for the response. When the check completes, data.registered reports whether that number was registered on WhatsApp at the time of the request. The caller can use the result immediately without polling another endpoint.

This is a narrow product contract. WA Lookup checks registration status; it does not identify the person behind the number, monitor account activity, or operate a messaging service. Keeping that scope explicit makes the returned field easier to use correctly.

Returned data Meaning Recommended action
code=0, registered=true The completed check reported registered Use the boolean result returned by this request
code=0, registered=false The completed check reported not registered Use false as the completed result
Non-zero business code The service returned no registration decision Do not invent a boolean; handle the error or retry according to the API docs

Why synchronous checks are useful

A synchronous result is useful when the next software step depends on a current registration answer. The application does not need to create a job, persist a polling token, or wait for a callback before it can classify the number.

Typical integrations include an internal form that checks one number, a support tool that verifies a record on demand, or a backend worker. For small lists, the synchronous batch endpoint accepts up to 100 E.164 identifiers and returns the completed batch in the initiating response. Clients should still control their own concurrency.

The main architectural benefit is determinism: a completed response contains one boolean registration decision. API errors and undetermined checks use the outer code, msg, and data envelope instead of adding more values to registered.

The request path, step by step

  1. Normalize the phone number — Convert a well-understood country calling code and national number into E.164 form. Do not guess missing country context.
  2. Send one check — Call the authenticated check endpoint with the normalized number and service_type=ws.
  3. Read the completed result — Consume data.registered when code=0; keep it unset when the API returns a non-zero business code.
  4. Store the observation time — Registration is a point-in-time result, so save when it was checked.
  5. Handle non-results separately — An invalid request or temporary failure needs correction or retry, not a false registration value.

Model the result without losing meaning

Avoid a generic field such as valid. It cannot distinguish a malformed input from a valid number that completed as unregistered. A small explicit record is safer:

Field Purpose
source_phone Preserves the value supplied by the source system
e164_phone Stores the canonical number submitted for checking
outcome Your application’s completed, retryable, or failed-request classification
registered Stores true or false only for a completed check
checked_at Records when the point-in-time observation was made
service_type Records which product contract produced the result

HTTP errors are not additional values for this record. If an application logs them, it should store the returned HTTP status and API code separately from registration observations.

A practical integration rule

Only branch on data.registered when the outer response has code=0.

That one rule prevents the most common interpretation error: treating a timeout, a rejected request, or a malformed number as if WhatsApp had reported the number unregistered. If the decision needs to be current at a later time, make a new synchronous check and save it as a new observation rather than silently changing the old timestamp.

Sources