API Documentation

Everything you need to integrate Telerify — resolve phone numbers to full Telegram profiles in under 400ms.

Quickstart

Send a single POST request with an international phone number and get the full profile back.

Request

curl -X POST https://telerify.com/api/v1/lookup \
  -H "Authorization: Bearer tlf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+33612345678"}'

Response

{
  "status":      "found",
  "telegramId":  "1364180491",
  "fullName":    "Sophie Martin",
  "username":    "@sophiem",
  "lastSeen":    "2026-07-04T14:02:00Z",
  "accountAge":  "Mar 2019",
  "accountType": "human",
  "isBot":       false,
  "isFake":      false,
  "isPremium":   false,
  "safetyScore": "safe",
  "latencyMs":   312,
  "creditsUsed": 1
}

Authentication

Pass your API key as a Bearer token in the Authorization header of every request.

Authorization: Bearer tlf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

tlf_live_…Live key

Production — credits are billed

tlf_test_…Test key

Sandbox — no data, always free

Manage your keys in Dashboard → API Keys.

Endpoints

POST/v1/lookup

Resolve one phone number to a Telegram profile.

{ "phone": "+33612345678" }

POST/v1/bulk

Resolve up to 500 numbers in one request (Pro+).

{ "phones": ["+33612345678", "+447911123456"] }

GET/v1/credits

Return current credit balance.

GET/v1/history

Return a paginated list of past lookups.

POST/v1/webhooks

{ "url": "https://your-app.com/webhook" }

Response fields

Field	Type	Description
`status`	`string`	"found" \| "not_found" \| "error"
`telegramId`	`string?`	Unique numeric Telegram user ID
`fullName`	`string?`	Full display name
`username`	`string?`	@handle if set
`bio`	`string?`	Profile description
`lastSeen`	`ISO date?`	Last online timestamp
`accountAge`	`string?`	Estimated account creation period
`accountType`	`string?`	"human" \| "bot"
`isBot`	`boolean?`	True if a Telegram bot
`isFake`	`boolean?`	Fake or scam account flag
`isPremium`	`boolean?`	Telegram Premium subscriber
`safetyScore`	`string?`	"safe" \| "unsafe"
`latencyMs`	`number`	API response time in ms
`creditsUsed`	`number`	0 if not found, 1 if found

Error codes

400invalid_phonePhone number format is invalid

401unauthorizedMissing or invalid API key

402insufficient_creditsNot enough credits

429rate_limitedToo many requests — slow down

500server_errorInternal error — retry after delay

SDKs

Official libraries for the most popular languages.

Python

pip install telerify

from telerify import Client

ts = Client("tlf_live_YOUR_KEY")
result = ts.lookup("+33612345678")

print(result.full_name)    # Sophie Martin
print(result.username)     # @sophiem
print(result.safety_score) # safe

Node.js

npm install telerify

const { Telerify } = require('telerify')

const ts = new Telerify('tlf_live_YOUR_KEY')
const result = await ts.lookup('+33612345678')

console.log(result.fullName)    // Sophie Martin
console.log(result.username)    // @sophiem
console.log(result.safetyScore) // safe

go get github.com/telerify/go-sdk

client := telerify.New("tlf_live_YOUR_KEY")
result, _ := client.Lookup("+33612345678")

fmt.Println(result.FullName)    // Sophie Martin
fmt.Println(result.Username)    // @sophiem
fmt.Println(result.SafetyScore) // safe

Webhooks

POST /v1/webhooks
{ "url": "https://your-app.com/webhook" }

// Telerify will POST to your URL:
{
  "event":  "lookup.completed",
  "phone":  "+33612345678",
  "result": { "status": "found", "fullName": "Sophie Martin", ... }
}

Validate webhook requests by checking the X-Telerify-Signature header against your webhook secret.