# AvatarLookup

> AvatarLookup is a public-avatar lookup platform. Every lookup answers one question: does this account publish a usable public avatar. Its core capability is a synchronous single lookup — submit one identifier to the REST API and the avatar state plus the image URL come back in the same HTTP response, with no task queue, no polling and no callbacks. Multi-identifier synchronous requests are also available, and an asynchronous bulk option covers whole lists and the platforms that have no realtime product.

## Products (realtime lookups)

Results arrive in the same HTTP response, for one identifier or for several sent in a single request.

- WhatsApp Avatar Lookup (`ws_avatar`): takes a phone number in E.164 form. Returns whether the number is on WhatsApp, whether it publishes a profile photo, and the image URL when it does.
- Email Avatar Lookup (`email_avatar`): takes a full email address. One product covers Gmail, Yandex and Mail.ru — the provider is resolved from the domain and returned as `provider`. Addresses on any other domain are rejected before any charge, because no upstream covers them.

## Response fields

Three fields come back on every successful lookup, and they answer three different questions. An account that does not exist cannot have an avatar, but an account that does exist may still publish none — both are results and both are charged.

- `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: `gmail`, `yandex` or `mailru`, derived from the domain, so it always has a value.

## API

- Realtime: `POST /api/v1/check` (one identifier) and `POST /api/v1/batch-check` (up to 100 identifiers in one request, one shared `service_type`). Both return results synchronously in the same HTTP response.
- Secondary, for whole lists and for the platforms without a realtime product: `POST /api/v1/bulk-tasks` (upload a file, returns a task id) and `GET /api/v1/bulk-tasks/{id}` (status and result download link).
- Authentication: API key from the dashboard. The same key and the same balance cover every product.
- The API path is `/api/v1`. Current per-request and per-task limits are documented in the API docs.

## Pricing

AvatarLookup charges per identifier: $0.01 for a completed lookup. Balance is drawn down as lookups run. Permanent balance does not expire or renew. A 30-day plan renews automatically every 30 days until auto-renewal is turned off; turning it off stops future charges without removing the current plan or balance. A rate-limited public demo lookup is available without signing in.

## Also available: asynchronous bulk lookup (secondary)

For whole lists, and for the platforms that have no realtime product, upload a file and download a result archive when the task finishes. Bulk products: `ws_avatar_batch`, `tg_avatar_batch` (Telegram by phone number), `tg_username_avatar_batch` (Telegram by username), `viber_avatar_batch`, `max_avatar_batch`, `line_avatar_batch` and `email_avatar_batch`. Phone-number products need a country picked at upload; the username and email products do not. The estimate is held when the task is submitted and the unanswered part is returned to the balance on settlement.

## Important Notes

- An avatar describes what the platform publishes at request time. Avatars are added, changed and removed at any time — a stored result is a record of that moment, not of today.
- It is not a reachability or activity check. An avatar does not mean the account is in use, online, or able to receive anything.
- No message, call or email is ever sent to the account being looked up. Lookups read what the platform already publishes.
- An empty `avatar_url` means «no public avatar», not «lookup failed». A lookup that actually failed or could not be determined returns an error code and is refunded.
- A result is not identity verification, not proof of ownership, and not consent to be contacted.

## Methodology and Guides

- [How avatar lookup works](https://avatarlookup.com/how-it-works): the lookup flow, what each field means, identifier formats, and interpretation boundaries.
- [API documentation](https://avatarlookup.com/api-docs): authentication, endpoints, response shape, and error codes.
- [MCP server](https://avatarlookup.com/mcp-docs): run lookups from Claude, Cursor, or any MCP client with an existing API key.
- [Pricing](https://avatarlookup.com/pricing): permanent top-ups and 30-day plans.