Telegram Username Profile Checker API
Retrieve Telegram activation status, nickname, and avatar, then analyze the avatar for gender, age, and skin tone. This product accepts usernames directly instead of phone numbers.
Input format
Upload a text file with one Telegram username per line. Accepted formats are username, @username, and t.me/username; full https://t.me/username links are also accepted.
OpenAI@Telegramt.me/durovA valid username is 5–32 characters, starts with a letter, and contains only letters, numbers, or underscores. Results preserve the original spelling, case, and prefix from the uploaded file.
Create a task
POST https://api.numberchecker.ai/v1/tasks
curl --location 'https://api.numberchecker.ai/v1/tasks' \--header 'X-API-Key: YOUR_API_KEY' \--form 'file=@"./usernames.txt"' \--form 'task_type="tg_username_profile"'| Parameter | Type | Required | Description |
|---|---|---|---|
file | file | Yes | Text file containing one Telegram username per line |
task_type | string | Yes | Set to tg_username_profile |
Successful task creation returns HTTP 202:
{ "task_id": "d7profile123example", "status": "pending", "total": 3, "message": "Task created successfully", "created_at": "2026-08-11T10:00:00Z"}Query task status
POST https://api.numberchecker.ai/v1/gettasks
curl --location 'https://api.numberchecker.ai/v1/gettasks' \--header 'X-API-Key: YOUR_API_KEY' \--form 'task_id="d7profile123example"'When status is exported, download the ZIP archive from result_url.
Result files
The ZIP archive contains activated.txt, unregistered.txt, all.csv, and result.xlsx.
all.csv and result.xlsx contain these fields:
| Field | Description | Example |
|---|---|---|
username | Original username representation from the uploaded file | @Telegram |
activated | Whether the Telegram username is active | yes, no |
nickname | Telegram display name returned for the username | Telegram |
avatar | Avatar URL; empty when unavailable | https://example.com/avatar.jpg |
gender | Gender inferred from the avatar; empty when unavailable | male, female |
age | Age or age range inferred from the avatar; empty when unavailable | 25 |
skin_color | Skin tone inferred from the avatar; empty when unavailable | light, dark |
The result does not include type or members fields. Image-analysis fields are inferred values and can be empty when the avatar is missing or unsuitable for analysis.
Task status response
{ "created_at": "2026-08-11T10:00:00Z", "updated_at": "2026-08-11T10:02:30Z", "task_id": "d7profile123example", "user_id": "YOUR_USER_ID", "status": "exported", "total": 3, "success": 3, "failure": 0, "result_url": "https://example.com/result.zip"}