TG Validator
接口参考

TG Validator API 文档

所有端点共用同一个 API Key 与余额。

项目值
Base URLhttps://tgvalidator.com
鉴权头X-API-Key: sk_your_api_key
响应结构{ code, msg, data }

本页不列价格；每款产品按成功检测计费。 查看定价

认证

使用在设置中创建的 API Key，并随每次请求一起发送。

鉴权头
X-API-Key: sk_your_api_key

妥善保管您的 API Key请始终从您的服务端发起请求；持有该 Key 的任何人都可以消耗您的账户余额。

同步检测

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

提交一个手机号，或在一次请求里提交最多 100 个，结果都在同一次响应里返回，不需要轮询也不需要回调。无法判定时返回 422 与业务码 42200，且不计费。多号请求保持提交顺序、每个标识独立计费，整批限时 300 秒，超时则整批失败并全额退款。

请求参数

字段类型说明
service_typestring产品码，取下面列出的任一产品。
identifierstring单号检测用：一个手机号。服务端会做归一化。
identifiersstring[]多号检测用：1~100 个手机号，响应按此顺序返回。

本类产品

Telegram 注册检测

tg手机号

通过同步 API 或 SaaS 网页后台确认号码是否已注册 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}

上传文件后立刻拿到任务号，之后按任务号查询；成功的响应里带 result_url 结果下载链接。对外只有提交与查询两个动作，轮询间隔不要短于 30 秒。

请求参数

字段类型说明
service_typestring批量产品码，取下面列出的任一产品。
countrystringISO 3166-1 国家码（如 US）。号码类任务必填：每个号码都要带国家码并属于这个国家（不符合的号码会被排除、不计费），也用它选路。multipart 时必须排在 file 之前。
filefile.txt 或 .csv，每行一个标识，不超过 max_file_bytes（默认 20MB）。
Idempotency-Keyheader可选，≤128 字符。同一个 key 重放返回原任务，不会重复建单。

本类产品

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 时，该行其余各列留空。
uid1234567890Telegram 用户 ID。
usernamealex_kim用户名，未设置时为空。
activedays9距上次在线的天数（整数），数值越小越近期。账号隐藏了精确在线时间时，Telegram 只给出大致范围，此时为近似值：0（最近）、7（一周内）、30（一月内）或 1000（很久以前）。

Telegram 批量资料检测

tg_profile_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_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 时，该行其余各列留空。
uid1234567890Telegram 用户 ID。
usernamealex_kim用户名，未设置时为空。
activedays9距上次在线的天数（整数），数值越小越近期。账号隐藏了精确在线时间时，Telegram 只给出大致范围，此时为近似值：0（最近）、7（一周内）、30（一月内）或 1000（很久以前）。
avatar_urlhttps://telegram.waavatar.xyz/v/example.jpg头像链接，没有头像时为空。
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、活跃天数与头像链接。

提交任务

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 时，该行其余各列留空。
uid1234567890Telegram 用户 ID；账号存在时也可能为空。
activedays9距上次在线的天数（整数），数值越小越近期。账号隐藏了精确在线时间时，Telegram 只给出大致范围，此时为近似值：0（最近）、7（一周内）、30（一月内）或 1000（很久以前）。账号没有公开任何在线信息时为空。
avatar_urlhttps://cdn5.telesco.pe/file/example.jpg头像链接，没有头像时为空。

余额查询

GET/api/v1/balance

查询账户当前余额（USD micros）。只读接口：不产生检测记录，也不扣费。

余额查询

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 注册检测采用同步响应，请根据返回码决定接收结果或稍后重试。

字段说明
每个用户最多 5 个请求在处理单号检测与多号检测共用这个上限，一次多号请求算一个请求，与号码数量无关。此外每个账号同时只能跑 1 个多号检测，第二个会被拒绝直到前一个结束。达到任一上限都会立即返回业务码 42901 并附带 Retry-After 响应头，不扣费，等已有请求结束后再提交即可。
单号 60 秒，多号 300 秒超过后返回业务码 50400，不计费；多号超时是整批失败，不返回部分结果，已扣费用全额退回。
多号单次最多 100 个号码结果按提交顺序、同等长度返回。每个账号同时只跑 1 个多号检测，上一批返回后再提交下一批。

错误码

业务码说明
40000不支持的 service_type 或字段冲突
40001JSON 请求体无效
40002号码无效
40100缺少或无效的 API Key
40200余额不足
42200暂时无法判定该号码。不返回 data，且本次不计费
42900次数配额已用完，或未完成订单数超限
429015 个在处理的请求名额已满，或该账号已有一个多号检测在跑；已有请求结束后可再次提交，拒绝请求不扣余额，响应带 Retry-After
50303平台此刻处理中的检测已达上限，不扣费；按 Retry-After 的秒数等待后重新提交同一请求
50400本次检测未在超时预算内完成，不计费，可直接重试；批量超时为整批失败并全额退款
50300检测服务维护中