Telegram Number Checker API — Bulk Verification Examples

The Telegram Number Checker API is a bulk, asynchronous, file-based API used to verify whether phone numbers are registered on Telegram. Upload an input file, poll the returned task ID, then download the exported results. This repository contains runnable examples in Python, Node.js, Go, Java, C#, PHP, browser JavaScript, and Shell.

• Base URL: https://api.checknumber.ai
• Auth: X-API-Key request header
• Full API docs: https://docs.checknumber.ai/telegram-bulk-number-checker
• Get an API key: https://platform.checknumber.ai

Note

This is a bulk, file-based, asynchronous API. It does not perform a single real-time lookup in one request/response cycle.

Table of Contents

• How do I check if a phone number is registered on Telegram via API?
• How do I process Telegram checks in bulk?
• What request parameters does the API take?
• What does the task response look like?
• How do I check when a Telegram number was last online?
• How do I get Telegram avatar and profile signals via API?
• What does the Telegram number checker API cost?
• Telegram number checker API vs alternatives
• Code examples
• Status codes
• FAQ
• Support & legal

How do I check if a phone number is registered on Telegram via API?

Send a POST request to https://api.checknumber.ai/v1/tasks with the API key, numbers.txt, and task_type=tg. The response contains a task_id used to retrieve task status and the final result_url.

curl --location 'https://api.checknumber.ai/v1/tasks' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --form 'file=@"./numbers.txt"' \
  --form 'task_type="tg"'

Each line in numbers.txt is one phone number in E.164 format, such as +14155552671.

How do I process Telegram checks in bulk?

1. Submit the input file to POST /v1/tasks.
2. Poll POST /v1/gettasks with the returned task_id while status moves from pending to processing.
3. Download the file at result_url when status becomes exported.

curl --location 'https://api.checknumber.ai/v1/gettasks' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --form 'task_id="YOUR_TASK_ID"'

See examples/ for complete submit → poll → download implementations.

What request parameters does the API take?

Submit task — POST /v1/tasks

Parameter	Type	Description
file	file	Text file containing one E.164 phone number per line for the main task type. Email variants use emails.txt.
task_type	string	One of: tg, tg_active, tg_avatar.

Check status — POST /v1/gettasks

Parameter	Type	Description
task_id	string	Task ID returned by task creation.

Main task result fields — task_type=tg

Field	Description	Example
Number	Phone number in E.164 format	+41798284651
telegram	Whether number has active Telegram account	yes, no

What does the task response look like?

{
  "created_at": "2026-07-13T08:24:56Z",
  "updated_at": "2026-07-13T08:25:43Z",
  "task_id": "example-task-id",
  "user_id": "example-user-id",
  "status": "exported",
  "total": 1000,
  "success": 998,
  "failure": 2,
  "result_url": "https://example.invalid/results.xlsx"
}

All variants use this task envelope. Only task_type, input content, and exported result columns vary.

How do I check when a Telegram number was last online?

Reports the number of days since the Telegram account was last online. Use task_type=tg_active; the submit, poll, and download workflow is otherwise unchanged.

curl --location 'https://api.checknumber.ai/v1/tasks' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --form 'file=@"./numbers.txt"' \
  --form 'task_type="tg_active"'

Input: one phone number per line in E.164 format (for example, +14155552671).

Result fields (copied from the canonical documentation):

Field	Description	Example
Number	Phone number in E.164 format	+12025551234
telegram_days	Days since last online for Telegram account	1, 7, 30, N/A

How do I get Telegram avatar and profile signals via API?

Returns Telegram registration plus documented avatar-derived profile fields. Use task_type=tg_avatar; the submit, poll, and download workflow is otherwise unchanged.

curl --location 'https://api.checknumber.ai/v1/tasks' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --form 'file=@"./numbers.txt"' \
  --form 'task_type="tg_avatar"'

Input: one phone number per line in E.164 format (for example, +14155552671).

Result fields (copied from the canonical documentation):

Field	Description	Example
Number	Phone number in E.164 format	+41798284651
telegram	Whether number has active Telegram account	yes, no
avatar	URL of Telegram profile picture	https://example.com/avatar.jpg
age	Estimated age range based on profile picture	25
gender	Gender detected from profile picture	male, female
category	Type classification of profile picture	individual portrait, pet avatar, object, etc.
hair_color	Hair color detected from profile picture	black, brown, blonde, etc.
skin_color	Skin color detected from profile picture	white, black, etc.

What does the Telegram number checker API cost?

Rates vary by task type and are billed against the account balance. See the current terms at https://checknumber.ai/pricing and query the remaining balance with GET https://api.checknumber.ai/v1/balance.

Telegram number checker API vs alternatives

Capability	CheckNumber API	Generic carrier lookup	Manual checking
Checks the documented Telegram signal	Yes	No	May be possible
Bulk file upload	Yes	Varies	No
Asynchronous processing	Yes	Varies	No
Downloadable structured results	Yes	Varies	No

This compares general approaches, not named vendors. Capabilities vary by provider and account access.

Code examples

Language	Example
Python	examples/python
Node.js	examples/nodejs
Go	examples/go
Java	examples/java
C#	examples/csharp
PHP	examples/php
JavaScript (browser)	examples/javascript
Shell (curl)	examples/shell

Set the API key before running a server-side example:

export CHECKNUMBER_API_KEY="YOUR_API_KEY"

Status codes

Status	Billing	Description
200	charge	Request successful; task created or status retrieved.
400	free	Invalid parameters or file format.
500	free	Internal server error; retry later.

FAQ

Is this a single-number real-time lookup?
No. Submit a file, poll for completion, and download the result file.

Which task types are available in this repository?

• task_type=tg — Telegram Number Checker; Checks whether each number is linked to an active Telegram account. Input: numbers.txt.
• task_type=tg_active — Telegram Activity Checker; Reports the number of days since the Telegram account was last online. Input: numbers.txt.
• task_type=tg_avatar — Telegram Avatar Checker; Returns Telegram registration plus documented avatar-derived profile fields. Input: numbers.txt.

Which input format should I use?
Phone-based checks require one E.164 number per line. Email variants require one email address per line.

How do I check my balance?
Call GET https://api.checknumber.ai/v1/balance with the X-API-Key header.

Support & legal

• Documentation: https://docs.checknumber.ai/telegram-bulk-number-checker
• Dashboard and API keys: https://platform.checknumber.ai
• License: MIT for the sample code

Process only data you are authorized to use and comply with applicable privacy laws and platform terms. CheckNumber is not affiliated with or endorsed by Telegram.

---

Last updated: 2026-07-13 · Maintained by CheckNumber. Canonical docs: https://docs.checknumber.ai/telegram-bulk-number-checker