📘 Developer Docs

TeleScan API

Check phone numbers against Telegram programmatically — drop it into your own website, panel, or automation in minutes.

💵 $35/month flat

♾️ Unlimited usage

⚡ 60 req/min

🌍 Works from anywhere

Base URL https://api.gramlab.click

Quickstart

Every request needs your API key. Get one from the bot, then check your first batch of numbers:

bash

# Replace tsk_live_<your_key> with your real key
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"] }'

javascript

const res = await fetch('https://api.gramlab.click/v1/check', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tsk_live_<your_key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ numbers: ['+15551234567', '+447911123456'] }),
});

const data = await res.json();
console.log(data.results);

python

import requests

resp = requests.post(
    "https://api.gramlab.click/v1/check",
    headers={"Authorization": "Bearer tsk_live_<your_key>"},
    json={"numbers": ["+15551234567", "+447911123456"]},
)

print(resp.json()["results"])

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 a Key). 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": "green" },
    { "number": "+447911123456", "status": "registered" }
  ]
}

Status values

Status	Meaning
`green`	Fresh — no Telegram account on this number
`banned`	Account exists but has been deleted/banned
`locked`	Account exists but is spam/flood restricted
`registered`	Active, usable Telegram account exists 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.