WA Lookup
Registration-check records passing through completed, unresolved, and refresh states
Keep completed observations and unresolved attempts distinct throughout the result lifecycle.

Registration status is an observation, not a permanent label

A completed WhatsApp registration check answers whether one E.164 number was reported as registered at the recorded check time.

The result can be useful immediately, but it should not be stored as an eternal property such as phone.is_valid. Phone numbers and platform registrations can change, and a later technical failure does not reverse an earlier completed result. A durable model therefore records both the decision and the context that produced it.

WA Lookup returns registration information synchronously. That makes it easy to save the observation at the exact point where the application receives it. The same model should still distinguish a completed check from a request that never produced a registration decision.

The minimum useful result record

Field Example Why it matters
source_phone Original submitted text Supports correction and audit without changing the source
e164_phone +17253100591 Identifies the normalized value actually checked
service_type ws Identifies the result contract
outcome completed Your application’s classification of a completed result or a failed request
registered true or false Stores the completed registration result
received_at Application timestamp Records when the synchronous response arrived
api_code 0 Keeps the outer API result separate from the registration observation

Only set registered for a completed decision. Log the HTTP status and API code separately when the application needs an error history; do not turn those responses into another registration value.

Store the three response shapes accurately

The documented contract has two completed result shapes and one separate error shape:

  1. Completed registered result — code=0 and data.registered=true.
  2. Completed unregistered result — code=0 and data.registered=false.
  3. No decision — a non-zero API code, with no registered value to store.

Invalid input, insufficient balance, concurrency limits, timeouts, maintenance, and internal failures use non-zero API codes. They are request errors, not values of the WhatsApp registration result.

Preserve history when a new check runs

If the application needs a newer status, append a new observation or version the existing record. Do not overwrite the old checked_at while retaining its result, and do not replace the last completed value with false merely because a refresh failed.

A simple current-state view can select the newest completed observation, while the underlying table keeps every attempt. That gives the application a current answer when one exists and still exposes whether a more recent attempt was unresolved.

Situation Latest completed result Separate request log
First check completes true true received at T1 Success at T1
Later API request returns an error true received at T1 HTTP/API error at T2
Later check completes false false received at T3 Success at T3

Choose refresh timing from the business decision

There is no universal expiry time for a registration result. The appropriate freshness window depends on how much delay the surrounding workflow can tolerate. An on-demand user action may call for a new synchronous check, while an analytical report may accept an older timestamp as long as its age is visible.

Define the rule explicitly:

  • what maximum result age the workflow accepts;
  • which non-zero API responses should trigger a later call;
  • which API errors the caller chooses to submit again after;
  • how concurrency limits and timeouts are respected;
  • how timestamps are displayed to operators.

The important point is not to market an old database value as real time. WA Lookup provides a synchronous current observation when called; the integrating application decides when it needs to call again.

The reliable storage principle

Store registration evidence as timestamped observations and store operational attempts as their own states.

This keeps registered=false meaningful, makes retries safer, and lets every interface say exactly when its displayed status was checked. It also matches the product boundary: WA Lookup supplies registration-check results, while the customer system owns retention, refresh policy, and downstream decisions.

Sources