Lookup methodology
How AvatarLookup checks an account's avatar
AvatarLookup answers one question per lookup: does this account publish a usable public avatar. This page covers the two realtime products, what each field means, the identifier formats, and where the result stops being valid.
Reviewed September 18, 2026
What happens during an avatar lookup?
You submit one identifier — a phone number for WhatsApp, an email address for the email product — and three fields come back in the same HTTP response: registered, avatar and avatar_url. No polling, no callbacks. The result describes what the platform publishes at that moment, nothing more.
Complete one lookup
This section covers the realtime products: the dashboard and the synchronous REST endpoints share one lookup service and one response meaning. Whole lists go through the asynchronous bulk option, covered at the end of this page.
- 1
Pick the source
service_type=ws_avatar takes a phone number. service_type=email_avatar takes an email address and covers Gmail, Yandex and Mail.ru in one product.
- 2
Submit one identifier
One per request, or up to 100 in one synchronous multi request. The whole batch shares a single service_type.
- 3
Read three fields
registered, avatar and avatar_url. Run a new lookup when you need a current state — avatars change.
Which identifier format to submit
Each product accepts exactly one identifier form. Sending the wrong form is rejected before any charge.
- WhatsApp: one phone number in E.164 form — a plus sign, the country code, then the subscriber number with no spaces or separators.
- Email: one full address. Only Gmail, Yandex and Mail.ru domains are accepted; any other domain is rejected before it is charged, because no upstream covers it.
- National number formats with leading zeros, spaces, dashes or brackets are not accepted. A rejected format is not a «no avatar» result.
What do the three fields mean?
They answer three different questions and must not be collapsed into one. An account that does not exist cannot have an avatar, but an account that does exist may still publish none — those are different results and they are charged the same.
- registered — whether the identifier has an account on that platform.
- avatar — whether that account publishes a public photo. False is a result, not a failure.
- avatar_url — the image address when avatar is true, an empty string otherwise. It points at the platform's own CDN and may expire on their schedule, so treat it as a pointer rather than an archive.
- provider — only on the email product: which of the three providers the address resolved to. It is derived from the domain, so it always has a value.
Use the result within its scope
A lookup reflects the state at request time. It is not identity verification and not permission to contact someone.
- An avatar does not confirm who owns the account, whether it is in use, or whether anyone is reading it.
- Avatars are added, changed and removed at any time. A result stored last month is a record of that moment, not of today.
- Nothing is sent to the account being looked up — the lookup reads what the platform already publishes.
Whole lists: the asynchronous option
The realtime multi endpoint covers most lists. Beyond that, submit the whole file as one asynchronous bulk task — that is also the only way to reach the platforms without a realtime product (Telegram, Viber, LINE, MAX).
- Upload a .txt or .csv with one identifier per line, from the bulk check page or through the API.
- Phone-number products need the country picked at upload; the username and email products do not.
- Balance is reserved for the valid lines on submit, you are charged only for identifiers that return a result, and the difference is refunded.
- The task runs in the background; download the result archive when it finishes. A failed task is refunded in full.