Запрос cURL
POST /api/v1/bulk-taskscurl -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 Демо в реальном времени
POST /api/v1/bulk-tasksservice_type=tg_profile_batchМассовый продукт tg_profile_batch
Массовая проверка профилей Telegram
ID пользователя, имя пользователя, дни активности, URL аватара, а также возраст, пол и тон кожи, оценённые по аватару, — по всему списку.
Дополнение для больших списков целиком — для нескольких номеров проверка в реальном времени отвечает в том же запросе. Проверка в реальном времени →
Контракт API
Два шага: отправьте файл, затем проверьте задачу
При отправке сразу возвращается id задачи; проверяйте задачу по этому id, и после успешного завершения ответ будет содержать ссылку для скачивания файла результата. Каждый запрос показан вместе со своим ответом.
1. Отправьте файл
id задачи возвращается сразу с preparing = true, пока файл подготавливается в фоне: некорректные строки, дубликаты и — для задач с номерами — номера без кода страны или из другой страны удаляются и не оплачиваются. Баланс резервируется за отправленные строки, а расчёт производится по завершении; разница возвращается.
Ответ: задача создана
200 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. Проверьте задачу
Опрашивайте по id задачи. После завершения подготовки submitted_lines = total + invalid_cnt + no_code_cnt + other_country_cnt + duplicate_cnt, где total — количество проверяемых и оплачиваемых номеров. Успешный ответ содержит количество успешных и неудачных проверок и ссылку для скачивания файла результата; задача, отклонённая при подготовке, получает статус failed с reason_detail, и средства возвращаются полностью.
Запрос cURL
GET /api/v1/bulk-tasks/{id}curl "https://tgvalidator.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
-H "X-API-Key: sk_your_api_key"Ответ: задача завершена
200 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"
}
}Как это работает
Что происходит с массовой задачей
Массовая проверка — это не увеличенная проверка в реальном времени, а схема «отправили один раз, выполняется в фоне, забрали позже». Держать страницу открытой не нужно: состояние задачи и результаты сохраняются в вашей панели.
01Загрузите файл
Файл .txt или .csv с одним номером на строку. Он передаётся потоком напрямую, ничего не записывается на диск.
02Предпроверка и резервирование
Очевидные проблемы (пустой файл, неверный формат, слишком мало строк) отклоняются при загрузке. Затем резервируется баланс, и файл подготавливается в фоне: удаляются некорректные строки, дубликаты и номера без кода страны или из другой страны, а также проверяется правило одной страны. Файл, не прошедший этот этап, завершается как неудавшаяся задача с полным возвратом средств; в противном случае проверяются только оставшиеся строки, а расчёт по задаче производится по её завершении.
03Выполнение в фоне
Задача выполняется самостоятельно — страницу можно закрыть. О сбое сообщается сразу, и средства возвращаются полностью.
04Скачайте результат
Заберите файл на странице массовой проверки. Вы платите только за номера, по которым действительно получен результат; разница возвращается.
Поля результата
Столбцы файла результата
Для скачивания предоставляется один файл CSV с этой полной таблицей.
Столбцы файла результата
identifier·17253100591— Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591).activated·true— Зарегистрирован ли номер в Telegram: true или false. Если значение не true, все остальные столбцы в этой строке остаются пустыми.uid·1234567890— ID пользователя Telegram.username·alex_kim— Имя пользователя; пусто, если у аккаунта его нет.activedays·9— Количество дней с последнего посещения аккаунта, целым числом — чем меньше, тем свежее. Если аккаунт скрывает точное время последнего посещения, Telegram раскрывает только диапазон, и значение приблизительное: 0 (недавно), 7 (в течение недели), 30 (в течение месяца) или 1000 (давно).avatar_url·https://telegram.waavatar.xyz/v/example.jpg— URL аватара; пусто, если у аккаунта нет аватара.age·31— Возраст, оценённый по аватару; пусто, если оценить невозможно.gender·male— Пол, оценённый по аватару: male или female; unknown, если распознать не удалось, пусто, если аватара нет.skin_color·white— Тон кожи, оценённый по аватару, например white, middle_eastern, east_asian; unknown, если распознать не удалось, пусто, если аватара нет.
Лучше всего подходит для
Когда выбирать этот продукт
Сегментация аудитории
agegenderskin_colorРазделяйте аудитории по признакам, оценённым по аватару, и выбирайте для каждого сегмента более подходящий подход к коммуникации.
Например: создайте отдельные списки для рассылки по возрасту и полу.
Целевое разделение списков
activatedactivedaysОтберите аккаунты, которые всё ещё используются, затем расставьте приоритеты сегментов по давности активности.
Например: начните с зарегистрированных сегментов, которые были недавно активны.
Сбор аватаров
avatar_urlusernameДополните зарегистрированные контакты ссылками на публичные аватары и именами пользователей, чтобы упростить последующую проверку.
Например: добавьте ссылки на публичные аватары в профили контактов CRM.
Первичная проверка подлинности аккаунтов
uidusernameavatar_urlИспользуйте ID пользователя, имя пользователя и аватар, чтобы отметить скудно заполненные записи, которым может потребоваться ручная проверка.
Например: отправьте неполные или необычные записи на ручную проверку.
Краткий ответ
Что такое «Проверка профиля» в массовом режиме?
Массовая проверка профилей Telegram возвращает профиль каждого зарегистрированного номера: ID пользователя, имя пользователя, дни активности, URL аватара, а также возраст, пол и тон кожи, оценённые по аватару. Создана для сегментации больших списков. Результат содержит только перечисленные здесь поля; история переписки и содержимое сообщений никогда не затрагиваются.
Чёткие границы
Ограничения этого продукта
- Это не подтверждение личности. Результат описывает состояние регистрации номера на платформе и не может подтвердить, кому принадлежит номер.
- История сообщений, содержимое переписки и любое закрытое содержимое аккаунта никогда не возвращаются.
- При отправке выберите страну, к которой относятся ваши номера. Список должен в основном состоять из номеров этой страны; соседние страны с общим телефонным кодом не считаются другими странами. Неподходящий список завершается как неудавшаяся задача с полным возвратом средств.
- Результаты отражают момент выполнения задачи. Для актуального состояния запустите её снова — сохранённые результаты автоматически не обновляются.
- Ссылки для скачивания имеют ограниченный срок действия. Скачайте файл вскоре после завершения задачи; если ссылка истекла, проверьте задачу снова, чтобы получить новую.
Когда подходит массовая проверка
Когда массовая проверка оправдана, а когда быстрее проверка в реальном времени
| Проверка в реальном времени | Массовая проверка | |
|---|---|---|
| Сколько номеров | 1 номер на одиночную проверку; несколько — в множественном запросе, точные лимиты указаны в документации API | Большой список целиком в одной задаче — текущий диапазон размеров указан на странице цен |
| Получение результатов | Сразу: одиночный и множественный эндпоинты отвечают в том же ответе; панель возвращает результаты по одному | Скачайте файл с результатом после завершения задачи |
| Страна / регион | Без ограничений — можно смешивать в одном запросе | При отправке выберите одну страну/регион; список должен в основном состоять из номеров этой страны, а при слишком большом числе номеров из других стран задача завершится ошибкой с полным возвратом |
| Формат результата | JSON, поля по каждому номеру | Файл результата (один CSV с полной таблицей) |
| Типичное применение | Проверка форм, запросы операторов, контроль перед отправкой | Очистка списков, фильтрация перед кампанией, очистка сохранённых данных |
FAQ по продукту
О продукте «Проверка профиля»
Когда использовать массовую проверку вместо проверки в реальном времени?
Используйте массовую проверку для большого списка целиком. Для нескольких номеров проверка в реальном времени отвечает в том же запросе, без планирования задачи.
Что происходит с некорректными номерами в файле?
Предпроверка отбрасывает некорректные строки, поэтому они не попадают в оплачиваемое количество. Из оставшихся номеров те, которые вышестоящий сервис не смог определить, тоже не оплачиваются. Вы платите только за номера, по которым действительно получен результат.
Сколько времени занимает задача?
Это зависит от количества номеров и продукта. После отправки страницу можно закрыть: задача выполняется в фоне, а результат будет ждать вас на странице массовой проверки.
Вернутся ли средства, если задача не удалась?
Да. За неудавшуюся задачу средства возвращаются полностью. Если задача выполнена, но по части номеров нет результата, эта часть возвращается автоматически. Разница между зарезервированной и фактически списанной суммой всегда возвращается.
Создайте аккаунт, чтобы отправить массовую задачу
Массовые проверки и проверки в реальном времени расходуют один баланс — ничего дополнительно включать не нужно. Зарегистрируйтесь и загрузите первый файл на странице массовой проверки.