How to store and refresh WhatsApp registration-check results

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	+14155552671	Identifies the normalized value actually checked
service_type	ws	Identifies the result contract
status	success	Preserves the exact result status returned by the API
registered	true or false	Stores the completed registration result
received_at	Application timestamp	Records when the synchronous response arrived
transaction_id	Returned check identifier	Helps trace the completed request

Keep registered nullable because the documented undetermined result contains no boolean decision. Do not create extra result statuses for HTTP errors; log their HTTP status and API error code separately if the application needs an error history.

Store the three response shapes accurately

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

1. Successful registered result — code=0, data.status=success, and data.registered=true.
2. Successful unregistered result — code=0, data.status=success, and data.registered=false.
3. Undetermined result — code=0, data.status=undetermined, data.registered=null, and data.charged_amount_micros=0.

Invalid input, insufficient balance, rate limits, concurrency limits, maintenance, and internal failures use non-zero API codes with data=null. 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;
• whether an undetermined response should trigger a later call;
• which API errors the caller chooses to submit again after;
• how concurrency and rate limits 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.