How a real-time WhatsApp registration check fits into a synchronous workflow

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
status=success, registered=true	The completed check reported registered	Use the boolean result returned by this request
status=success, registered=false	The completed check reported not registered	Use false as the completed result
status=undetermined, registered=null	The service returned no registration decision	Do not invent a boolean; the request is not charged

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 that processes a list one item at a time. The API remains single-number and synchronous in every case. A client that processes many records is responsible for controlling its own queue and concurrency.

The main architectural benefit is determinism: a successful completed response contains one boolean registration decision. The documented undetermined response contains no boolean decision. API errors such as invalid input or rate limiting use the outer code, msg, and data=null error 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 returned status — Consume data.registered when data.status is success; leave it unset when the documented result is undetermined.
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
status	Preserves the exact success or undetermined value returned in result data
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 returned result has status=success.

That one rule prevents the most common interpretation error: treating a timeout, rate limit, or 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.