Single vs Bulk Avatar Check: Choosing by Data Source

Learn how to choose between single and bulk avatar analysis based on your data source, from direct image uploads to asynchronous messaging platform batches.

Choosing between a single vs bulk avatar check depends on whether your workflow starts with visual assets or raw identifiers. AvatarLookup structures analysis across three clear tiers. When an image asset is already available, image profile analysis performs direct visual analysis on the file. When all you hold is an identifier, WhatsApp and supported email domains provide realtime single checks or synchronous multi-identifier lookups. For large volumes on Telegram, Viber, LINE, Zalo, and MAX, asynchronous bulk-file tasks process identifier lists through staged CSV exports. Understanding this source-specific division ensures teams integrate the appropriate request pattern for each data pipeline.

Image Profile Analysis for Existing Visual Assets

Image profile analysis serves as the primary evaluation tier when teams already possess a graphic file or hosted visual asset. Instead of querying an external communications network using a phone number or handle, this workflow evaluates the image directly. The submission relies on multipart file upload, accepting common web image formats such as JPEG, PNG, WebP, or GIF.

The system derives an algorithmic content fingerprint from the submitted file rather than linking it to a personal account identifier. The resulting payload provides structured portrait attributes, including a picture category classification alongside algorithmic estimates for age, gender, skin color, and hair color. Teams use this method to screen user-submitted profile pictures during account onboarding, audit legacy photo repositories, or categorize inbound creative media. Because the analysis evaluates visual data independent of external platform presence, it operates on demand for individual media files.

Realtime Identifier Checks for WhatsApp and Email

When all you hold is an identifier rather than an image asset, realtime lookups query whether a public avatar is accessible on supported services. This capability applies specifically to WhatsApp phone numbers and supported webmail domains, covering Gmail, Yandex, and Mail.ru addresses.

Teams implement synchronous queries using POST /api/v1/check for single records or POST /api/v1/batch-check for grouped identifier sets. The multi-check endpoint handles batches of 1 to 100 identifiers within a single request, returning an ordered JSON array. For email profiles, the check indicates whether the address can receive mail alongside any public portrait attributes. In synchronous responses, the exists property serves as an execution indicator where true confirms a result was generated, while false denotes an invalid input or undetermined result. This pattern supports live lead routing, registration screening, and responsive contact enrichment workflows.

Asynchronous Bulk-File Tasks for Messaging Networks

High-volume data processing across broader social ecosystems shifts from realtime calls to asynchronous file-based execution. Telegram, Viber, MAX, LINE, and Zalo profile services function exclusively through bulk tasks. High-volume WhatsApp and email collections can also be queued through bulk processing to handle extended lists without managing continuous socket connections.

Bulk workflows require plain TXT or CSV files listing one identifier per row. Spreadsheet formats such as XLSX are unsupported. Phone number files must contain standardized digits without spaces or leading symbols, submitted alongside an ISO 3166-1 country code. Telegram username tasks accept usernames with or without prefix symbols, bypassing regional country parameters. Because per-product file limits and minimum identifier thresholds apply, teams should review current platform API documentation before preparing input sets.

End-to-End Bulk Lifecycle and CSV Result Ingestion

Operating an asynchronous bulk task follows a three-stage integration pattern designed for background job queues:

• Task Creation: The client system submits the formatted file using POST /api/v1/bulk-tasks. For phone services, the country code precedes the file payload in multipart transmission. The platform returns a unique task ID.
• Polling Status: The client monitors job progression by calling GET /api/v1/bulk-tasks/{id}. Automated poll cycles should occur no more frequently than every 30 seconds to prevent unnecessary gateway overhead.
• CSV Ingestion: Upon successful completion, the status endpoint delivers a secure CSV download URL valid for 12 hours. Refreshing the task query extends expiring links if data pipelines experience ingestion delays.

Output schemas reflect the underlying product family. Email batches return identifier, activated, and avatar image paths, while Telegram files return platform identifiers, activity days, and visual attribute estimates. Pipeline engineers must parse each product file according to its documented column specifications.

FAQ

Which messaging platforms support realtime single checks?

Realtime single checks and synchronous multi-lookups are available exclusively for WhatsApp and supported email domains, specifically Gmail, Yandex, and Mail.ru addresses. Other messaging platforms, including Telegram, Viber, LINE, Zalo, and MAX, operate strictly as asynchronous bulk-file workflows rather than immediate synchronous checks.

What file requirements apply to phone-number bulk tasks?

Bulk tasks require formatted TXT or CSV files containing one identifier per line without spreadsheet formatting. For phone-based lists, numbers require country-coded digits stripped of plus signs or punctuation. Teams submit an ISO 3166-1 country parameter preceding the file in multipart submissions, with per-product file limits detailed in official API documentation.

How should teams interpret an empty avatar or exists=false response?

In synchronous multi-checks, exists=false signifies an invalid identifier, an undetermined lookup, or an unreached endpoint rather than definitive proof of account non-existence. Similarly, an empty avatar URL or nonhuman category reflects algorithmically undetermined visual fields, not profile verification or identity confirmation.

Learn More

Choose the product information that fits the next step in your workflow.

• Visit the product website →