TeleScan API

Check phone numbers against Telegram programmatically — integrate it into your own website or number-checking panel.

💵 $35/month

♾️ Unlimited usage

⚡ 60 req/min

Authentication

Send your API key as a Bearer token on every request:

header

Authorization: Bearer tsk_live_<your_key>

Keys are shown once, when issued or regenerated via the bot (🔌 Get API). There's no way to retrieve a lost key — only regenerate it, which invalidates the old one.

Check numbers

POST /v1/check

Checks up to 100 phone numbers per request. Each number is checked live against Telegram.

Request

bash

curl -X POST https://api.gramlab.click/v1/check \
  -H "Authorization: Bearer tsk_live_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["+15551234567", "+447911123456"]
  }'

Response

json

{
  "results": [
    { "number": "+15551234567", "status": "fresh" },
    { "number": "+447911123456", "status": "green" }
  ]
}

Status values

Status	Meaning
`green`	Active, usable Telegram account
`banned`	Account exists but has been deleted/banned
`locked`	Account exists but is spam/flood restricted
`fresh`	No Telegram account on this number

Usage

GET /v1/usage

Returns your current key status.

Request

bash

curl https://api.gramlab.click/v1/usage \
  -H "Authorization: Bearer tsk_live_<your_key>"

Response

json

{
  "keyPrefix": "tsk_live_ab12cd34",
  "active": true,
  "expiresAt": "2026-09-05T18:55:26.161Z",
  "lastUsedAt": "2026-08-05T19:02:11.000Z"
}

Errors

Errors are always JSON: { "error": { "code", "message" } }

HTTP	Code	Meaning
400	`INVALID_BODY` / `INVALID_NUMBERS` / `TOO_MANY_NUMBERS`	Malformed request
401	`MISSING_KEY` / `INVALID_KEY`	Auth header missing or key invalid
402	`ACCESS_EXPIRED`	API access subscription has expired
429	`RATE_LIMITED`	More than 60 requests/minute on this key
503	`RATE_LIMITED_UPSTREAM` / `SERVICE_UNAVAILABLE`	Checking temporarily unavailable — retry shortly

Rate limits

Up to 60 requests per minute per key. This protects shared checking capacity — it isn't a usage cap on your monthly plan, which is genuinely unlimited.