Handling avatar_url Values Returned by WA Lookup

The avatar_url field is the part of a ws_avatar response that most often surprises an integration, because it is optional and because a URL is a very different thing to store than a boolean.

WA Lookup returns avatar_url only when the upstream service supplies one for the account, so an integration reading ws_avatar responses needs a data model where the URL is optional and separate from the avatar boolean it accompanies.

Model the boolean and the URL separately

The avatar boolean and the avatar_url string answer different questions: whether an avatar was detected, and where it could be retrieved. Collapsing them into one nullable column loses the first answer whenever the second is absent, and absence is a normal outcome rather than an edge case. Two columns keeps both answers readable.

Decide whether you store the URL at all

Some integrations only need the boolean, in which case discarding the URL removes a class of questions about retention entirely. If you do keep it, keep the check date beside it, because profile information changes and a stored URL is a snapshot of what was true at check time rather than a permanent address.

Treat retrieval as a separate concern

Fetching whatever a URL points to is a different operation from running the check, with its own failure modes and its own timing. Keeping the two apart means a retrieval problem never looks like a check problem in your logs, which matters when you are trying to work out why a batch looks wrong.

Handle absence without branching everywhere

Normalize the response once at the boundary of your integration — turn the optional field into an explicit representation your code understands — instead of testing for presence at every call site. Absent values are common enough that scattered checks become the main source of avoidable bugs.

FAQ

Should avatar_url be stored indefinitely?

Store it with the check date if you store it at all, since profile information changes and the value is a snapshot rather than a permanent address.

What does an absent avatar_url indicate?

That the upstream service did not supply one for that account at check time. The avatar boolean still reports whether an avatar was detected.

Does retrieval happen as part of the check?

No. The check returns fields; retrieving what a URL points to is a separate operation with its own failure modes.