Sign up and contact support to get 100 free checks.Sign up free
TG Validator
Live demoPOST /api/v1/bulk-tasksservice_type=tg_profile_batch

Telegram Bulk Profile Check

User ID, username, active days, avatar URL, and age, gender and skin tone estimated from the avatar — across a whole list.

An add-on for whole large lists — for a handful of numbers the realtime check answers in the same request. Realtime check →

View API contractSign Up

Two steps: submit the file, then check the task

Read the full API docs Open API Keys

Submitting returns a task id right away; check the task by that id and, once it succeeds, the response carries the result file download link. Each request is shown with its own response.

1. Submit the file

The task id comes back straight away with preparing set to true while the file is prepared in the background: invalid lines, duplicates and — for number tasks — numbers without a country code or from another country are removed and not charged. Balance is reserved for the submitted lines and settled on completion; the difference is refunded.

cURL requestPOST /api/v1/bulk-tasks
curl -X POST "https://tgvalidator.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: task created200 OK
{
  "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"
  }
}

2. Check the task

Poll by task id. Once preparation finishes, submitted_lines = total + invalid_cnt + no_code_cnt + other_country_cnt + duplicate_cnt, where total is what is checked and charged. A successful response carries the success and failure counts and the result file download link; a task refused during preparation is failed with reason_detail and refunded in full.

cURL requestGET /api/v1/bulk-tasks/{id}
curl "https://tgvalidator.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
Response: task finished200 OK
{
  "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"
  }
}

What happens to a bulk task

Bulk is not realtime made bigger — it is submit once, run in the background, collect later. You do not need to keep the page open; task state and results stay in your dashboard.

  1. 01Upload the file

    A .txt or .csv with one number per line. It is streamed straight through; nothing is written to disk.

  2. 02Precheck and reserve

    Obvious problems (an empty file, the wrong format, too few lines) are rejected on upload. Balance is then reserved and the file is prepared in the background: invalid lines, duplicates and numbers without a country code or from another country are removed, and the single-country rule is checked. A file that fails there ends as a failed task, refunded in full; otherwise only the remaining lines are checked, and the task is settled on completion.

  3. 03Run in the background

    The task runs on its own — close the page if you like. A failure is reported straight away and fully refunded.

  4. 04Download the result

    Collect the file from the bulk check page. You pay only for numbers that actually returned a result; the difference is refunded.

Columns in the result file

The download is a single CSV file containing this full table.

Result file columns

  • identifier · 12345678900 — The submitted number as plain digits with the country code, no plus sign or spaces (e.g. 12345678900).
  • 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, middle_eastern, east_asian; unknown when it cannot be recognised, empty when there is no avatar.

When to reach for this one

Audience segmentation

agegenderskin_color

Split audiences by attributes estimated from the avatar, then use a more suitable outreach approach for each segment.

For example: create separate outreach lists by age and gender.

Targeted list splits

activatedactivedays

Filter for accounts still in use, then prioritise segments by how recently they were active.

For example: start with registered segments that were active recently.

Avatar asset collection

avatar_urlusername

Fill in public avatar links and usernames for registered contacts to make later review easier.

For example: add public avatar links back to CRM contact profiles.

First-pass account authenticity

uidusernameavatar_url

Use the user ID, username and avatar to flag sparse entries that may need manual review.

For example: send incomplete or unusual entries for manual review.

What is the bulk Profile check?

Telegram bulk profile check returns the profile of each registered number: user ID, username, active days, the avatar URL, and age, gender and skin tone estimated from the avatar. Built for segmenting large lists. The result contains only the fields listed here; chat history and message content are never involved.

Limits of this product

  • It is not identity verification. A result describes the number's registration state on the platform; it cannot confirm who owns the number.
  • It never returns message history, conversation content, or any private account content.
  • Choose the country your numbers belong to when submitting. The list should be essentially that one country; neighbours sharing a dialling code do not count as cross-country. A list that does not qualify ends as a failed task and is refunded in full.
  • Results reflect the moment the task ran. Run it again for a fresh state — stored results are never refreshed for you.
  • Download links expire. Fetch the file soon after the task finishes; if a link expires, check the task again for a new one.

When bulk is worth it — and when realtime is faster

Realtime checkBulk check
How many numbers1 number per single check; several per multi request — exact caps are in the API docsA whole large list in one task — the current size range is on the pricing page
Getting resultsRight away: single and multi-endpoint answer in the same response; the dashboard returns them one by oneDownload a result file when the task finishes
Country / regionNo restriction — mix freely in one requestPick one country/region on submission; the list should be essentially that country, and too many numbers from elsewhere fail the task with a full refund
Result shapeJSON, fields per numberResult file (one CSV with the full table)
Typical useForm validation, agent lookups, pre-send gatingList hygiene, pre-campaign filtering, stored-data cleanup

Realtime check · View pricing

About Profile check

When should I use bulk instead of a realtime check?

Use bulk for a whole large list. For a handful of numbers the realtime check answers in the same request, with no task to schedule.

What happens to invalid numbers in the file?

The precheck drops malformed lines, so they never enter the billable count. Of the numbers that remain, any the upstream cannot resolve are not charged either. You pay only for numbers that actually return a result.

How long does a task take?

It depends on the number count and the product. You can close the page after submitting; the task runs in the background and the result waits for you on the bulk check page.

Do I get refunded if it fails?

Yes. A failed task is refunded in full. If the task succeeds but some numbers return nothing, that portion is refunded automatically. The difference between the reserved amount and what was actually charged always comes back.

Create an account to submit a bulk task

Bulk and realtime checks draw on the same balance — nothing extra to enable. Sign up and upload your first file on the bulk check page.

Sign Up View pricing