How to Check if a Number Is on Telegram (Checker API)

Published August 23, 2026 Β· UpdatedOctober 16, 2026

userHash is the only field get-about and get-picture accept. A phone number, @username, or user:<id> is rejected there. check-exists mints that 24-hour ticket when a peer exists on Telegram; the two heavier calls spend it. This Telegram number checker article is the handoff: mint once, reuse while the window is open, mint again after it closes.

You do not log in a Telegram account. You do need an authorized platform key from the dashboard (sign in if you do not have one). The Python below reads OPENDATA_API_KEY from the server environment; curl uses the YOUR_API_KEY placeholder. Query URLs carry the key, so keep them out of logs, screenshots, shared links and source control, and call from your server. Opening this page or copying an example does not send a lookup. Running a command does, and it spends credits.

The field everything else waits on

Bio and avatar wait on userHash. That ticket waits on one public input: peer. Three forms are accepted:

  • +phone: digits with a leading plus, for example +8613800138000.
  • @username or a bare username.
  • user:<id> for a numeric Telegram user ID.

requests encodes the plus for you. If you paste a raw URL, write the plus as %2B or it is read as a space and the miss looks like a bad number.

HTTP success is not business success. Read the HTTP status first, then the gateway envelope {code, message, data}. Gateway code=200 is business success. A clean miss is still business success: exists is false and reason is a code such as PHONE_NOT_OCCUPIED or USERNAME_NOT_OCCUPIED. That tells you whether the number or the handle was the problem. Do not retry a clean miss as a transport failure.

When exists is true, the payload includes the numeric Telegram user id, the username when the peer has one, the display name, and userHash. The phone and handle below are documented shapes, not guaranteed hits.

curl --get 'https://api.opendata-api.com/api/project/telegram/check-exists?key=YOUR_API_KEY' \
  --data-urlencode 'peer=+8613800138000'

--data-urlencode keeps the leading plus intact. A username is the right peer when a handle is all you have.

Mint a userHash, then spend it

The hash is bound to the peer you just checked. It is valid for 24 hours, reusable until it expires, and never forwarded as a Telegram credential β€” the gateway resolves the subject server-side. Consume operations take only userHash. A missing, unknown or expired hash is rejected (HTTP 400 and a gateway business failure) without a bio or photo lookup. Call check-exists again to mint a fresh ticket.

There is no batch operation. Deduplicate and normalize first (phones need + and a country code), call check-exists once per peer, and store exists, reason, identity fields, userHash and an issued-at timestamp together. Spend the ticket only on peers you still need to enrich, and only while issued_at + 24h is in the future.

import base64
import os
from datetime import datetime, timedelta, timezone

import requests

BASE = "https://api.opendata-api.com/api/project/telegram"
KEY = os.environ["OPENDATA_API_KEY"].strip()
TTL = timedelta(hours=24)


def call(operation, **params):
    try:
        response = requests.get(
            f"{BASE}/{operation}",
            params={"key": KEY, **params},
            timeout=30,
        )
    except requests.RequestException:
        raise RuntimeError("Transport failure; inspect redacted logs") from None
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP failure: {response.status_code}")
    try:
        envelope = response.json()
    except ValueError:
        raise RuntimeError("Expected JSON") from None
    if not isinstance(envelope, dict) or envelope.get("code") != 200:
        raise RuntimeError("Gateway business failure; review redacted diagnostics")
    payload = envelope.get("data")
    if not isinstance(payload, dict):
        raise RuntimeError("Unexpected operation payload")
    return payload


def mint(peer):
    found = call("check-exists", peer=peer)  # requests encodes "+"
    if found.get("exists") is False:
        return {"peer": peer, "exists": False, "reason": found.get("reason")}
    user_hash = found.get("userHash")
    if found.get("exists") is not True or not user_hash:
        raise RuntimeError("check-exists did not mint a userHash")
    return {
        "peer": peer,
        "exists": True,
        "username": found.get("username"),
        "userHash": user_hash,
        "issued_at": datetime.now(timezone.utc),
    }


def still_live(ticket):
    issued = ticket.get("issued_at")
    return isinstance(issued, datetime) and datetime.now(timezone.utc) - issued < TTL


def enrich(ticket, want_photo=False):
    if not ticket.get("exists"):
        return ticket
    if not still_live(ticket):
        raise RuntimeError("userHash expired; mint again with check-exists")
    about = call("get-about", userHash=ticket["userHash"])
    profile = {
        "peer": ticket["peer"],
        "exists": True,
        "username": ticket.get("username") or about.get("username"),
        "about": about.get("about") or None,
    }
    if want_photo:
        picture = call("get-picture", userHash=ticket["userHash"])
        if picture.get("pictureSet") and picture.get("data"):
            profile["photo"] = base64.b64decode(picture["data"])
        else:
            profile["pictureSet"] = False
    return profile


# Documented peer shapes only β€” not guaranteed hits.
ticket = mint("+8613800138000")
print(enrich(ticket) if ticket.get("exists") else ticket)
handle = mint("@some_username")
print(enrich(handle, want_photo=True) if handle.get("exists") else handle)

The photo call is optional. Existence plus bio often answers the question; skipping get-picture saves a request per contact. Re-check on a schedule rather than on every touch: usernames and bios change, and a hash older than 24 hours is worthless until you mint again.

Telegram and WhatsApp are not interchangeable. Telegram accepts a public username and returns a user id; WhatsApp is number-only and its registration flag is three-state. If you are choosing a channel, read WhatsApp vs Telegram lookup APIs. Checking is not sending: send and read Telegram messages in Python uses a logged-in account. Combining channels is covered in the lead verification workflow.

Bio and avatar after the hash

Pass only the stored hash. Do not send peer again.

get-about returns public bio text plus the numeric user id and username. An empty about means the user has no bio or hides it. That is a normal answer, not a failure, and the API does not fabricate text. If the peer is a group or channel rather than a user, the call returns a bad-request business code instead of a bio β€” stop, and do not decode an about field that is not there.

get-picture returns the profile photo base64-encoded in data with MIME type image/jpeg, because Telegram photos have no public URL. Decode data to bytes. pictureSet=false means no photo or a hidden one; that is not a transport error.

Try the checker on the Telegram Number Validation page, or read the check-exists, get-about and get-picture references. See pricing when you are ready to go beyond free credits.

Mistakes that burn the 24-hour window

  • Sending peer to bio or avatar. Those operations do not accept it. The hash is the identity.
  • Reminting on every refresh. Cache userHash with issued_at. Call check-exists again only after expiry, or when you need a new existence verdict.
  • Retrying get-picture after expiry. An expired hash is rejected before upstream. Mint first, then spend.
  • Confusing HTTP 200 with "on Telegram". Business success can still be exists=false. A consume call with a dead hash is HTTP 400, not a hidden bio.
  • Leaving + unencoded in a hand-built URL. The plus becomes a space; reason then looks like a bad number.
  • Enriching misses. Skip get-about and get-picture unless exists is true and the hash is still live.
  • Treating empty about or pictureSet=false as a bug. Hidden or unset profile fields are valid answers.
  • Logging the full request URL. It contains the platform key. Redact key= everywhere, and never ship the key in a browser.
  • Forcing a phone when you only have a handle. peer already accepts @username, a bare username, and user:<id>.
  • Spending a Telegram hash on another project. Each mint is bound to the peer you checked here.

Only process contacts you have a legitimate basis to look up. The 24-hour window is long enough to enrich a shortlist; it is not a reason to re-check every row on every page view.