Reference

AvatarLookup API reference

Every endpoint shares one API key and one balance.

Item	Value
Base URL	https://avatarlookup.com
Auth header	X-API-Key: sk_your_api_key
Response envelope	{ code, msg, data }

Prices are not listed here; every product is billed per successful check. See pricing

Authentication

Use an API key created in Settings and send it with every request.

Auth header

X-API-Key: sk_your_api_key

Keep your API key secretAlways call this endpoint from your server. Anyone holding the key can spend your balance.

Synchronous checks

POST/api/v1/checkPOST/api/v1/batch-checkPOST/api/v1/image/profile

Submit one identifier, or up to 100 in one request, and read the result in the same response. No polling, no callbacks. An undetermined result returns 422 with code 42200 and is not charged. A multi request keeps the input order, bills each identifier independently, and has 300 seconds to finish — if it does not, the whole request fails and every charge is refunded. Image profiling uses its own endpoint, /api/v1/image/profile, and takes an image instead of an identifier.

Parameters

Field	Type	Description
`service_type`	string	Product code, one of the products listed below.
`identifier`	string	Single check: one identifier. The server normalizes it.
`identifiers`	string[]	Multi check: 1 to 100 identifiers. The response preserves this order.
`file`	file	Image profiling: one portrait image (multipart upload). There is no `identifier`.

Products in this group

Image profile analysisimage_profileUpload any picture and get its portrait attributes: estimated age, gender, image type, hair colour and skin tone.Product page
WhatsApp avatar analysisws_profileCheck whether a number has a WhatsApp avatar, get the image URL, and read the portrait attributes of that avatar.Product page
Email avatar analysisemail_profileCheck whether an email account has an avatar and read its portrait attributes. Covers Gmail, Yandex and Mail.ru.Product page

Image profile analysis

image_profileimage

Upload any picture and get its portrait attributes: estimated age, gender, image type, hair colour and skin tone.

Single check

POST/api/v1/image/profile

Request

curl -X POST "https://avatarlookup.com/api/v1/image/profile" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=image_profile \
  -F file=@portrait.jpg

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "image_profile",
    "identifier": "img:7013df96c540904a4b7ba295e9162ab2",
    "category": "individual portrait",
    "age": 39,
    "gender": "male",
    "skin_color": "white",
    "hair_color": "brown"
  }
}

Response fields

Field	Type	Description
`identifier`	string	Fingerprint of the submitted picture, derived from its content. The same picture always yields the same value.
`category`	string	What the picture is: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar or object. unknown when no portrait could be produced.
`age`	integer	Estimated age as an integer, accurate to about 3 years and clamped to 0-80. Omitted when it could not be estimated (for example when no gender was determined).
`gender`	string	male, female or unknown.
`skin_color`	string	Descriptive skin tone, for example white, east_asian or hispanic. Treat it as an open set; unknown when not determined.
`hair_color`	string	Descriptive hair colour, for example black, brown, blond or gray white. Treat it as an open set; unknown when not determined.

WhatsApp avatar analysis

ws_profilephone

Check whether a number has a WhatsApp avatar, get the image URL, and read the portrait attributes of that avatar.

Single check

POST/api/v1/check

Request

curl -X POST "https://avatarlookup.com/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws_profile", "identifier": "+17253100591" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_profile",
    "identifier": "+17253100591",
    "registered": true,
    "avatar": true,
    "avatar_url": "https://pps.whatsapp.net/v/example.jpg",
    "category": "individual portrait",
    "age": 39,
    "gender": "male",
    "skin_color": "white",
    "hair_color": "brown"
  }
}

Response fields

Field	Type	Description
`registered`	boolean	Whether the number is registered on WhatsApp.
`avatar`	boolean	Whether an avatar is set.
`avatar_url`	string	URL of the avatar; empty string when no photo is set.
`category`	string	What the picture is: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar or object. unknown when no portrait could be produced.
`age`	integer	Estimated age as an integer, accurate to about 3 years and clamped to 0-80. Omitted when it could not be estimated (for example when no gender was determined).
`gender`	string	male, female or unknown.
`skin_color`	string	Descriptive skin tone, for example white, east_asian or hispanic. Treat it as an open set; unknown when not determined.
`hair_color`	string	Descriptive hair colour, for example black, brown, blond or gray white. Treat it as an open set; unknown when not determined.

Multi check

POST/api/v1/batch-check

Request

curl -X POST "https://avatarlookup.com/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws_profile", "identifiers": ["+17253100591", "+14155550000", "12345"] }'

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_profile",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "registered": true,
        "avatar": true,
        "avatar_url": "https://pps.whatsapp.net/v/example.jpg",
        "category": "individual portrait",
        "age": 39,
        "gender": "male",
        "skin_color": "white",
        "hair_color": "brown"
      },
      {
        "identifier": "+14155550000",
        "exists": true,
        "registered": false,
        "avatar": false,
        "avatar_url": "",
        "category": "unknown",
        "gender": "unknown",
        "skin_color": "unknown",
        "hair_color": "unknown"
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Response fields

Field	Type	Description
`exists`	boolean	Whether this identifier produced a result. false means the format was invalid, the result was undetermined, or the check failed; when false, none of the fields below are present.
`registered`	boolean	Whether the account exists on that platform (for an email address: whether it is reachable). Present only when exists is true, with the same meaning as the single lookup.
`avatar`	boolean	Whether an avatar is set.
`avatar_url`	string	URL of the avatar; empty string when no photo is set.
`category`	string	What the picture is: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar or object. unknown when no portrait could be produced.
`age`	integer	Estimated age as an integer, accurate to about 3 years and clamped to 0-80. Omitted when it could not be estimated (for example when no gender was determined).
`gender`	string	male, female or unknown.
`skin_color`	string	Descriptive skin tone, for example white, east_asian or hispanic. Treat it as an open set; unknown when not determined.
`hair_color`	string	Descriptive hair colour, for example black, brown, blond or gray white. Treat it as an open set; unknown when not determined.

Email avatar analysis

email_profileemail

Check whether an email account has an avatar and read its portrait attributes. Covers Gmail, Yandex and Mail.ru.

Single check

POST/api/v1/check

Request

curl -X POST "https://avatarlookup.com/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "email_profile", "identifier": "alex.kim@gmail.com" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "email_profile",
    "identifier": "alex.kim@gmail.com",
    "registered": true,
    "avatar": true,
    "avatar_url": "https://lh3.googleusercontent.com/a/example",
    "category": "individual portrait",
    "age": 39,
    "gender": "male",
    "skin_color": "white",
    "hair_color": "brown"
  }
}

Response fields

Field	Type	Description
`registered`	boolean	Whether the email address is reachable (can receive mail).
`avatar`	boolean	Whether an avatar is set.
`avatar_url`	string	URL of the avatar; empty string when no avatar is set.
`category`	string	What the picture is: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar or object. unknown when no portrait could be produced.
`age`	integer	Estimated age as an integer, accurate to about 3 years and clamped to 0-80. Omitted when it could not be estimated (for example when no gender was determined).
`gender`	string	male, female or unknown.
`skin_color`	string	Descriptive skin tone, for example white, east_asian or hispanic. Treat it as an open set; unknown when not determined.
`hair_color`	string	Descriptive hair colour, for example black, brown, blond or gray white. Treat it as an open set; unknown when not determined.

Multi check

POST/api/v1/batch-check

Request

curl -X POST "https://avatarlookup.com/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "email_profile", "identifiers": ["alex.kim@gmail.com", "no.such.user@gmail.com", "not-an-email"] }'

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "email_profile",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      {
        "identifier": "alex.kim@gmail.com",
        "exists": true,
        "registered": true,
        "avatar": true,
        "avatar_url": "https://lh3.googleusercontent.com/a/example",
        "category": "individual portrait",
        "age": 39,
        "gender": "male",
        "skin_color": "white",
        "hair_color": "brown"
      },
      {
        "identifier": "no.such.user@gmail.com",
        "exists": true,
        "registered": false,
        "avatar": false,
        "avatar_url": "",
        "category": "unknown",
        "gender": "unknown",
        "skin_color": "unknown",
        "hair_color": "unknown"
      },
      {
        "identifier": "not-an-email",
        "exists": false
      }
    ]
  }
}

Response fields

Field	Type	Description
`exists`	boolean	Whether this identifier produced a result. false means the format was invalid, the result was undetermined, or the check failed; when false, none of the fields below are present.
`registered`	boolean	Whether the account exists on that platform (for an email address: whether it is reachable). Present only when exists is true, with the same meaning as the single lookup.
`avatar`	boolean	Whether an avatar is set.
`avatar_url`	string	URL of the avatar; empty string when no avatar is set.
`category`	string	What the picture is: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar or object. unknown when no portrait could be produced.
`age`	integer	Estimated age as an integer, accurate to about 3 years and clamped to 0-80. Omitted when it could not be estimated (for example when no gender was determined).
`gender`	string	male, female or unknown.
`skin_color`	string	Descriptive skin tone, for example white, east_asian or hispanic. Treat it as an open set; unknown when not determined.
`hair_color`	string	Descriptive hair colour, for example black, brown, blond or gray white. Treat it as an open set; unknown when not determined.

Asynchronous checks

POST/api/v1/bulk-tasksGET/api/v1/bulk-tasks/{id}

Upload a file and get a task id straight away, then check that id until it succeeds. The successful response carries result_url, the result download link. Only two actions exist: submit and check. Poll no more often than once every 30 seconds.

Parameters

Field	Type	Description
`service_type`	string	Bulk product code, one of the products listed below.
`country`	string	ISO 3166-1 code such as `US`. Required for number tasks: every number must include its country code and belong to this country (numbers that do not are left out and not charged); it also selects routing. In multipart it must come before `file`.
`file`	file	A `.txt` or `.csv` with one identifier per line, up to `max_file_bytes` (20MB by default).
`Idempotency-Key`	header	Optional, up to 128 characters. Replaying the same key returns the original task instead of creating a second one.

Products in this group

WhatsApp avatar analysis · Bulkws_profile_batchUpload a whole file of numbers: WhatsApp avatar URL plus what the avatar shows — category, age, gender, skin tone and hair colour.Product page
Telegram number profile · Bulktg_profile_batchUpload numbers: Telegram user ID, username, active days and avatar URL, plus age, gender and skin tone recognised from the avatar.Product page
Telegram username profile · Bulktg_username_profile_batchUpload Telegram usernames: user ID, active days and avatar URL for each account.Product page
Viber number profile · Bulkviber_profile_batchUpload numbers: Viber member ID, active days and avatar URL, plus category, age, gender and skin tone recognised from the avatar.Product page
MAX number profile · Bulkmax_profile_batchUpload numbers: MAX user ID, avatar URL and gender.Product page
LINE avatar analysis · Bulkline_profile_batchUpload numbers: LINE user ID and avatar URL, plus category, age, gender, skin tone and hair colour recognised from the avatar.Product page
Zalo number profile · Bulkzalo_profile_batchUpload numbers: Zalo user ID and avatar URL, plus category, age, gender and skin tone recognised from the avatar.Product page
Email avatar check · Bulkemail_avatar_batchUpload Gmail, Yandex or Mail.ru addresses: whether each one is deliverable, and its avatar.Product page

WhatsApp avatar analysis · Bulk

ws_profile_batchphone1,000–500,000 per task

Upload a whole file of numbers: WhatsApp avatar URL plus what the avatar shows — category, age, gender, skin tone and hair colour.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=ws_profile_batch \
  -F country=US \
  -F file=@numbers.txt

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_profile_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_profile_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	17253100591	The submitted number as plain digits with the country code, no plus sign or spaces (e.g. 17253100591).
`activated`	true	Whether the number is registered on WhatsApp: true or false. When it is not true, every other column in that row is left empty.
`avatar_url`	https://pps.waavatar.xyz/v/example.jpg	Avatar URL; empty when the account has no avatar.
`category`	individual portrait	What the avatar shows: individual portrait, group photo, cartoon avatar, pet avatar, landscape, object and so on; unknown when it cannot be recognised, empty when there is no avatar.
`age`	31	Age estimated from the avatar; empty when it cannot be estimated.
`gender`	male	Gender estimated from the avatar: male or female; unknown when it cannot be recognised, empty when there is no avatar.
`skin_color`	east_asian	Skin tone estimated from the avatar, e.g. white, asian, east_asian; unknown when it cannot be recognised, empty when there is no avatar.
`hair_color`	black	Hair colour estimated from the avatar, e.g. black, brown; unknown when it cannot be recognised, empty when there is no avatar.

Telegram number profile · Bulk

tg_profile_batchphone1,000–500,000 per task

Upload numbers: Telegram user ID, username, active days and avatar URL, plus age, gender and skin tone recognised from the avatar.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=tg_profile_batch \
  -F country=US \
  -F file=@numbers.txt

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_profile_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_profile_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	17253100591	The submitted number as plain digits with the country code, no plus sign or spaces (e.g. 17253100591).
`activated`	true	Whether the number is registered on Telegram: true or false. When it is not true, every other column in that row is left empty.
`uid`	1234567890	Telegram user ID.
`username`	alex_kim	Username, empty when the account has none.
`activedays`	9	Days since the account was last seen, as a whole number — smaller is more recent. When the account hides its exact last-seen time, Telegram only reveals a range, and the value is an approximation: 0 (recently), 7 (within a week), 30 (within a month) or 1000 (a long time ago).
`avatar_url`	https://telegram.waavatar.xyz/v/example.jpg	Avatar URL; empty when the account has no avatar.
`age`	31	Age estimated from the avatar; empty when it cannot be estimated.
`gender`	male	Gender estimated from the avatar: male or female; unknown when it cannot be recognised, empty when there is no avatar.
`skin_color`	white	Skin tone estimated from the avatar, e.g. white, asian, east_asian; unknown when it cannot be recognised, empty when there is no avatar.

Telegram username profile · Bulk

tg_username_profile_batchusername1,000–500,000 per task

Upload Telegram usernames: user ID, active days and avatar URL for each account.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=tg_username_profile_batch \
  -F file=@usernames.txt

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_username_profile_batch",
    "status": "processing",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_username_profile_batch",
    "status": "success",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	alex_kim	The submitted username, without @ or t.me/ (e.g. alex_kim).
`activated`	true	Whether the username belongs to an existing Telegram account: true or false. When it is not true, every other column in that row is left empty.
`uid`	1234567890	Telegram user ID; can be empty even for an existing account.
`activedays`	9	Days since the account was last seen, as a whole number — smaller is more recent. When the account hides its exact last-seen time, Telegram only reveals a range, and the value is an approximation: 0 (recently), 7 (within a week), 30 (within a month) or 1000 (a long time ago). Can be empty when the account reveals no last-seen information.
`avatar_url`	https://cdn5.telesco.pe/file/example.jpg	Avatar URL; empty when the account has no avatar.

Viber number profile · Bulk

viber_profile_batchphone1,000–500,000 per task

Upload numbers: Viber member ID, active days and avatar URL, plus category, age, gender and skin tone recognised from the avatar.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=viber_profile_batch \
  -F country=US \
  -F file=@numbers.txt

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "viber_profile_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "viber_profile_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	17253100591	The submitted number as plain digits with the country code, no plus sign or spaces (e.g. 17253100591).
`activated`	true	Whether the number is registered on Viber: true or false. When it is not true, every other column in that row is left empty.
`uid`	A5qCVDb3jPU=	Viber member ID.
`activedays`	3	Days since the account was last online — smaller is more recent.
`avatar_url`	https://viber.waavatar.xyz/v/example.jpg	Avatar URL; empty when the account has no avatar.
`category`	individual portrait	What the avatar shows: individual portrait, group photo, cartoon avatar, pet avatar, landscape, object and so on; unknown when it cannot be recognised, empty when there is no avatar.
`age`	31	Age estimated from the avatar; empty when it cannot be estimated.
`gender`	male	Gender estimated from the avatar: male or female; unknown when it cannot be recognised, empty when there is no avatar.
`skin_color`	white	Skin tone estimated from the avatar, e.g. white, asian, east_asian; unknown when it cannot be recognised, empty when there is no avatar.

MAX number profile · Bulk

max_profile_batchphone1,000–500,000 per task

Upload numbers: MAX user ID, avatar URL and gender.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=max_profile_batch \
  -F country=US \
  -F file=@numbers.txt

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "max_profile_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "max_profile_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	17253100591	The submitted number as plain digits with the country code, no plus sign or spaces (e.g. 17253100591).
`activated`	true	Whether the number is registered on MAX: true or false. When it is not true, every other column in that row is left empty.
`uid`	343064807	MAX user ID.
`avatar_url`	https://i.oneme.ru/i?r=example	Avatar URL; empty when the account has no avatar.
`gender`	male	Gender of the account: male or female; empty when unknown.

LINE avatar analysis · Bulk

line_profile_batchphone2,000–500,000 per task

Upload numbers: LINE user ID and avatar URL, plus category, age, gender, skin tone and hair colour recognised from the avatar.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=line_profile_batch \
  -F country=US \
  -F file=@numbers.txt

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "line_profile_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 2027,
    "total": 2027,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "line_profile_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 2027,
    "total": 2000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 24,
    "preparing": false,
    "success_cnt": 1980,
    "failure_cnt": 20,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	17253100591	The submitted number as plain digits with the country code, no plus sign or spaces (e.g. 17253100591).
`activated`	true	Whether the number is registered on LINE: true or false. When it is not true, every other column in that row is left empty.
`uid`	u5158553776c28d9164035c4fd0a07cd4	LINE user ID.
`avatar_url`	https://profile.line-scdn.net/example	Avatar URL; empty when the account has no avatar.
`category`	individual portrait	What the avatar shows: individual portrait, group photo, cartoon avatar, pet avatar, landscape, object and so on; unknown when it cannot be recognised, empty when there is no avatar.
`age`	31	Age estimated from the avatar; empty when it cannot be estimated.
`gender`	male	Gender estimated from the avatar: male or female; unknown when it cannot be recognised, empty when there is no avatar.
`skin_color`	east_asian	Skin tone estimated from the avatar, e.g. white, asian, east_asian; unknown when it cannot be recognised, empty when there is no avatar.
`hair_color`	black	Hair colour estimated from the avatar, e.g. black, brown; unknown when it cannot be recognised, empty when there is no avatar.

Zalo number profile · Bulk

zalo_profile_batchphone1,000–500,000 per task

Upload numbers: Zalo user ID and avatar URL, plus category, age, gender and skin tone recognised from the avatar.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=zalo_profile_batch \
  -F country=US \
  -F file=@numbers.txt

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "zalo_profile_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "zalo_profile_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	17253100591	The submitted number as plain digits with the country code, no plus sign or spaces (e.g. 17253100591).
`activated`	true	Whether the number is registered on Zalo: true or false. When it is not true, every other column in that row is left empty.
`uid`	452114152	Zalo user ID.
`avatar_url`	https://s160-ava-talk.zadn.vn/example.jpg	Avatar URL; empty when the account has no avatar.
`category`	individual portrait	What the avatar shows: individual portrait, group photo, cartoon avatar, pet avatar, landscape, object and so on; unknown when it cannot be recognised, empty when there is no avatar.
`age`	31	Age estimated from the avatar; empty when it cannot be estimated.
`gender`	male	Gender estimated from the avatar: male or female; unknown when it cannot be recognised, empty when there is no avatar.
`skin_color`	asian	Skin tone estimated from the avatar, e.g. white, asian, east_asian; unknown when it cannot be recognised, empty when there is no avatar.

Email avatar check · Bulk

email_avatar_batchemail1,000–500,000 per task

Upload Gmail, Yandex or Mail.ru addresses: whether each one is deliverable, and its avatar.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=email_avatar_batch \
  -F file=@emails.txt

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "email_avatar_batch",
    "status": "processing",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "email_avatar_batch",
    "status": "success",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	alex.kim@gmail.com	The submitted address, in lower case.
`activated`	true	Whether the address is deliverable at that provider — whether it can receive mail: true or false. When it is not true, every other column in that row is left empty.
`avatar`	true	Whether an avatar is set: true or false. avatar_url can still be empty when the image is not available.
`avatar_url`	https://lh3.googleusercontent.com/a/example	The avatar URL; empty when no URL is available.

Balance

GET/api/v1/balance

Read the current account balance in USD micros. Read-only: it creates no check record and charges nothing.

Balance

GET/api/v1/balance

Request

curl "https://avatarlookup.com/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

Concurrency, timeouts, and retry behavior

Avatar lookups are synchronous. Use the returned code to decide whether to accept the result or retry later.

Field	Description
`5 requests in flight per user`	Single and multi checks share this limit, and a multi request counts as one request no matter how many identifiers it carries. On top of that, only one multi check per account runs at a time; a second one is rejected until the first finishes. Hitting either limit returns code 42901 immediately with no charge, plus a Retry-After header — resubmit once an in-flight request finishes.
`60s single, 300s multi`	Exceeding the time limit returns code 50400 with no charge. A multi check that times out fails as a whole — no partial results, and the full amount is refunded.
`A multi check takes up to 100 identifiers`	Results preserve submission order and length. One multi check per account runs at a time; submit the next batch once the previous one has returned.

Error codes

Code	Description
`40000`	Unsupported service type or conflicting request fields
`40001`	Invalid JSON body
`40002`	Invalid identifier
`40100`	Missing or invalid API key
`40200`	Insufficient balance
`42200`	The identifier could not be determined at this time. No data is returned and the request is not charged
`42900`	A usage quota is exhausted, or there are too many unfinished orders
`42901`	All five in-flight request slots are occupied, or a multi check is already running on this account; submit after an in-flight request finishes. The rejected request is not charged and carries a Retry-After header
`50303`	The service is at capacity right now; not charged. Wait for the Retry-After seconds and resubmit the same request
`50400`	The check did not finish within its timeout and is not charged; retry it. A batch timeout fails the whole batch and refunds the full amount
`50300`	Validation service maintenance