Reference

TG Validator API reference

Every endpoint shares one API key and one balance.

Item	Value
Base URL	https://tgvalidator.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-check

Submit one phone number, 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.

Parameters

Field	Type	Description
`service_type`	string	Product code, one of the products listed below.
`identifier`	string	Single check: one phone number. The server normalizes it.
`identifiers`	string[]	Multi check: 1 to 100 phone numbers. The response preserves this order.

Products in this group

Telegram Registration ChecktgConfirm whether a number is registered on Telegram — useful for checking a contact list before you send.Product page

Telegram Registration Check

tgphone

Confirm whether a number is registered on Telegram — useful for checking a contact list before you send.

Single check

POST/api/v1/check

Request

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

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "tg",
    "identifier": "+17253100591",
    "registered": true
  }
}

Response fields

Field	Type	Description
`registered`	boolean	Whether the number is registered on Telegram.

Multi check

POST/api/v1/batch-check

Request

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

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "tg",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "registered": true
      },
      {
        "identifier": "+14155550000",
        "exists": true,
        "registered": false
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Response fields

Field	Type	Description
`exists`	boolean	Whether this number 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 number is registered. Present only when exists is true, with the same meaning as the single check.

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

Telegram Bulk Registration Check

tg_batchphone1,000–500,000 per task

Upload a whole file of numbers, find out which ones are registered on Telegram, and download the result file when it finishes.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://tgvalidator.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=tg_batch \
  -F country=US \
  -F [email protected]

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_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://tgvalidator.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_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.

Telegram Bulk Activity Check

tg_active_batchphone1,000–500,000 per task

Registration status plus user ID, username and active days — days since each account was last seen — across a whole list.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://tgvalidator.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=tg_active_batch \
  -F country=US \
  -F [email protected]

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_active_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://tgvalidator.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_active_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).

Telegram Bulk Profile Check

tg_profile_batchphone1,000–500,000 per task

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

Submit a task

POST/api/v1/bulk-tasks

Request

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 [email protected]

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://tgvalidator.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, middle_eastern, east_asian; unknown when it cannot be recognised, empty when there is no avatar.

Telegram Bulk Username Check

tg_username_batchusername1,000–500,000 per task

Upload a list of Telegram usernames and confirm which ones belong to real accounts.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://tgvalidator.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=tg_username_batch \
  -F [email protected]

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_username_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://tgvalidator.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_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.

Telegram Bulk Username Profile Check

tg_username_profile_batchusername1,000–500,000 per task

User ID, active days and avatar URL for a whole list of usernames.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://tgvalidator.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=tg_username_profile_batch \
  -F [email protected]

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://tgvalidator.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.

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://tgvalidator.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

Telegram registration checks are synchronous. Use the returned code to decide whether to accept the result or retry.

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 numbers 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 numbers`	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 number
`40100`	Missing or invalid API key
`40200`	Insufficient balance
`42200`	The number 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