TG Validator
Справочник

TG Validator Справочник API

Все эндпоинты используют один ключ API и один баланс.

ПараметрЗначение
Базовый URLhttps://tgvalidator.com
Заголовок аутентификацииX-API-Key: sk_your_api_key
Обёртка ответа{ code, msg, data }

Цены здесь не указаны; каждый продукт оплачивается за успешную проверку. Посмотреть цены

Аутентификация

Используйте ключ API, созданный в настройках, и передавайте его с каждым запросом.

Заголовок аутентификации
X-API-Key: sk_your_api_key

Храните ключ API в секретеВсегда вызывайте этот эндпоинт со своего сервера. Любой, у кого есть ключ, может расходовать ваш баланс.

Синхронные проверки

POST/api/v1/checkPOST/api/v1/batch-check

Отправьте один номер телефона или до 100 номеров в одном запросе и получите результат в том же ответе. Без опроса и обратных вызовов. Неопределённый результат возвращает 422 с кодом 42200 и не оплачивается. Множественный запрос сохраняет порядок ввода, тарифицирует каждый идентификатор независимо и должен завершиться за 300 секунд — иначе весь запрос завершается неудачей и все списания возвращаются.

Параметры

ПолеТипОписание
service_typestringКод продукта — один из продуктов, перечисленных ниже.
identifierstringОдиночная проверка: один номер телефона. Сервер нормализует его.
identifiersstring[]Множественная проверка: от 1 до 100 номеров телефонов. Ответ сохраняет этот порядок.

Продукты этой группы

Проверка регистрации в Telegram

tgтелефон

Узнайте, зарегистрирован ли номер в Telegram, — удобно для проверки списка контактов перед рассылкой.

Одиночная проверка

POST/api/v1/check
Запрос
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
  }
}
Поля ответа
ПолеТипОписание
registeredbooleanЗарегистрирован ли номер в Telegram.

Множественная проверка

POST/api/v1/batch-check
Запрос
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"] }'
Ответ
{
  "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
      }
    ]
  }
}
Поля ответа
ПолеТипОписание
existsbooleanПолучен ли результат по этому номеру. false означает, что формат недопустим, результат не определён или проверка не удалась; при false ни одно из полей ниже не возвращается.
registeredbooleanЗарегистрирован ли номер. Присутствует, только если exists равно true; значение то же, что и при одиночной проверке.

Асинхронные проверки

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

Загрузите файл и сразу получите id задачи, затем проверяйте этот id, пока задача не завершится успешно. Успешный ответ содержит result_url — ссылку для скачивания результата. Действий всего два: отправка и проверка. Опрашивайте не чаще одного раза в 30 секунд.

Параметры

ПолеТипОписание
service_typestringКод массового продукта — один из продуктов, перечисленных ниже.
countrystringКод ISO 3166-1, например US. Обязателен для задач с номерами: каждый номер должен содержать код страны и относиться к этой стране (остальные номера исключаются и не оплачиваются); также определяет маршрутизацию. В multipart должен идти перед file.
filefileФайл .txt или .csv с одним идентификатором на строку, размером до max_file_bytes (по умолчанию 20MB).
Idempotency-KeyheaderНеобязательный, до 128 символов. Повторная отправка с тем же ключом возвращает исходную задачу вместо создания новой.

Продукты этой группы

Массовая проверка регистрации в Telegram

tg_batchтелефон1 000–500 000 на задачу

Загрузите целый файл номеров, узнайте, какие из них зарегистрированы в Telegram, и скачайте файл с результатом после завершения.

Отправка задачи

POST/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_batch \
  -F country=US \
  -F file=@numbers.txt
Ответ
{
  "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"
  }
}

Проверка задачи

GET/api/v1/bulk-tasks/{id}
Запрос
curl "https://tgvalidator.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
Ответ
{
  "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"
  }
}
Столбцы результата
Полепример:Описание
identifier17253100591Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591).
activatedtrueЗарегистрирован ли номер в Telegram: true или false.

Массовая проверка активности в Telegram

tg_active_batchтелефон1 000–500 000 на задачу

Статус регистрации плюс ID пользователя, имя пользователя и дни активности — сколько дней прошло с последнего посещения каждого аккаунта — по всему списку.

Отправка задачи

POST/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_active_batch \
  -F country=US \
  -F file=@numbers.txt
Ответ
{
  "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"
  }
}

Проверка задачи

GET/api/v1/bulk-tasks/{id}
Запрос
curl "https://tgvalidator.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
Ответ
{
  "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"
  }
}
Столбцы результата
Полепример:Описание
identifier17253100591Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591).
activatedtrueЗарегистрирован ли номер в Telegram: true или false. Если значение не true, все остальные столбцы в этой строке остаются пустыми.
uid1234567890ID пользователя Telegram.
usernamealex_kimИмя пользователя; пусто, если у аккаунта его нет.
activedays9Количество дней с последнего посещения аккаунта, целым числом — чем меньше, тем свежее. Если аккаунт скрывает точное время последнего посещения, Telegram раскрывает только диапазон, и значение приблизительное: 0 (недавно), 7 (в течение недели), 30 (в течение месяца) или 1000 (давно).

Массовая проверка профилей Telegram

tg_profile_batchтелефон1 000–500 000 на задачу

ID пользователя, имя пользователя, дни активности, URL аватара, а также возраст, пол и тон кожи, оценённые по аватару, — по всему списку.

Отправка задачи

POST/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
Ответ
{
  "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"
  }
}

Проверка задачи

GET/api/v1/bulk-tasks/{id}
Запрос
curl "https://tgvalidator.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
Ответ
{
  "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"
  }
}
Столбцы результата
Полепример:Описание
identifier17253100591Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591).
activatedtrueЗарегистрирован ли номер в Telegram: true или false. Если значение не true, все остальные столбцы в этой строке остаются пустыми.
uid1234567890ID пользователя Telegram.
usernamealex_kimИмя пользователя; пусто, если у аккаунта его нет.
activedays9Количество дней с последнего посещения аккаунта, целым числом — чем меньше, тем свежее. Если аккаунт скрывает точное время последнего посещения, Telegram раскрывает только диапазон, и значение приблизительное: 0 (недавно), 7 (в течение недели), 30 (в течение месяца) или 1000 (давно).
avatar_urlhttps://telegram.waavatar.xyz/v/example.jpgURL аватара; пусто, если у аккаунта нет аватара.
age31Возраст, оценённый по аватару; пусто, если оценить невозможно.
gendermaleПол, оценённый по аватару: male или female; unknown, если распознать не удалось, пусто, если аватара нет.
skin_colorwhiteТон кожи, оценённый по аватару, например white, middle_eastern, east_asian; unknown, если распознать не удалось, пусто, если аватара нет.

Массовая проверка имён пользователей Telegram

tg_username_batchимя пользователя1 000–500 000 на задачу

Загрузите список имён пользователей Telegram и узнайте, какие из них принадлежат реальным аккаунтам.

Отправка задачи

POST/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_username_batch \
  -F file=@usernames.txt
Ответ
{
  "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"
  }
}

Проверка задачи

GET/api/v1/bulk-tasks/{id}
Запрос
curl "https://tgvalidator.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
Ответ
{
  "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"
  }
}
Столбцы результата
Полепример:Описание
identifieralex_kimОтправленное имя пользователя без @ и t.me/ (например, alex_kim).
activatedtrueПринадлежит ли имя пользователя существующему аккаунту Telegram: true или false.

Массовая проверка профилей по именам пользователей Telegram

tg_username_profile_batchимя пользователя1 000–500 000 на задачу

ID пользователя, дни активности и URL аватара для целого списка имён пользователей.

Отправка задачи

POST/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_username_profile_batch \
  -F file=@usernames.txt
Ответ
{
  "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"
  }
}

Проверка задачи

GET/api/v1/bulk-tasks/{id}
Запрос
curl "https://tgvalidator.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
Ответ
{
  "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"
  }
}
Столбцы результата
Полепример:Описание
identifieralex_kimОтправленное имя пользователя без @ и t.me/ (например, alex_kim).
activatedtrueПринадлежит ли имя пользователя существующему аккаунту Telegram: true или false. Если значение не true, все остальные столбцы в этой строке остаются пустыми.
uid1234567890ID пользователя Telegram; может быть пустым даже для существующего аккаунта.
activedays9Количество дней с последнего посещения аккаунта, целым числом — чем меньше, тем свежее. Если аккаунт скрывает точное время последнего посещения, Telegram раскрывает только диапазон, и значение приблизительное: 0 (недавно), 7 (в течение недели), 30 (в течение месяца) или 1000 (давно). Может быть пустым, если аккаунт не раскрывает сведений о последнем посещении.
avatar_urlhttps://cdn5.telesco.pe/file/example.jpgURL аватара; пусто, если у аккаунта нет аватара.

Баланс

GET/api/v1/balance

Получение текущего баланса аккаунта в микродолларах USD. Только чтение: запись о проверке не создаётся, списаний нет.

Баланс

GET/api/v1/balance
Запрос
curl "https://tgvalidator.com/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"
Ответ
{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

Параллельность, тайм-ауты и повторные попытки

Проверки регистрации в Telegram синхронны. По возвращённому code решайте, принять результат или повторить запрос.

ПолеОписание
5 одновременных запросов на пользователяОдиночные и множественные проверки делят этот лимит, причём множественный запрос считается одним запросом независимо от количества номеров в нём. Кроме того, на один аккаунт одновременно выполняется только одна множественная проверка; вторая отклоняется, пока не завершится первая. При достижении любого из лимитов сразу возвращается code 42901 без списания и заголовок Retry-After — отправьте запрос повторно после завершения одного из выполняющихся запросов.
60 с для одиночной, 300 с для множественнойПри превышении лимита времени возвращается code 50400 без списания. Множественная проверка, превысившая время ожидания, завершается неудачей целиком — без частичных результатов, и вся сумма возвращается.
Множественная проверка — до 100 номеровРезультаты сохраняют порядок и количество отправленных номеров. Для одного аккаунта одновременно выполняется одна множественная проверка; отправляйте следующий пакет после того, как вернётся предыдущий.

Коды ошибок

КодОписание
40000Неподдерживаемый тип сервиса или конфликтующие поля запроса
40001Недопустимое тело JSON
40002Недопустимый номер
40100Ключ API отсутствует или недействителен
40200Недостаточно средств на балансе
42200Номер не удалось определить в данный момент. Данные не возвращаются, и запрос не оплачивается
42900Исчерпана квота использования или слишком много незавершённых заказов
42901Заняты все пять слотов для выполняющихся запросов или на этом аккаунте уже выполняется множественная проверка; отправьте запрос после завершения одного из выполняющихся. Отклонённый запрос не оплачивается и содержит заголовок Retry-After
50303Сервис сейчас работает на пределе мощности; без списания. Подождите указанное в Retry-After число секунд и отправьте тот же запрос повторно
50400Проверка не завершилась за отведённое время и не оплачивается; повторите её. Превышение времени пакета приводит к ошибке всего пакета и полному возврату суммы
50300Техобслуживание сервиса проверки