Telegram Phone Number API Options: Bot API, Client API or a Registration Check API

A developer comparison of the Telegram Bot API, the Telegram client API and a registration check API for work that involves phone numbers.

There is no single Telegram phone number API. The Telegram Bot API only receives a phone number when a user chooses to share it, the Telegram client API works through a real user account and its credentials, and a registration check API such as TG Validator answers whether a submitted number is registered on Telegram. Pick the one that matches the job: collecting a number from a willing user, automating your own account, or checking numbers you already hold.

What developers mean by a Telegram phone number API

Searches for "telegram phone number api" usually come from one of three jobs:

1. Collect a user's number inside a bot, for example to link a Telegram chat to a customer account.
2. Automate a Telegram user account, for example to manage contacts or build a custom client.
3. Check numbers you already hold, for example to flag which CRM contacts have a Telegram account before choosing a channel.

Each job maps to a different interface with different credentials, limits and responsibilities. Choosing the wrong one is the most common reason integrations stall.

Bot API: receiving a number the user chooses to share

The Telegram Bot API does not look users up by phone number. A bot receives a number only when the user sends it:

• A reply keyboard button with request_contact set asks the user to share their own phone number as a contact. The reference notes this works in private chats only.
• The shared message carries a Contact object containing the phone number and, optionally, the user's Telegram identifier.

This is the right tool when you want a customer to connect their Telegram chat to your service with explicit action on their side. It cannot check a list of numbers, and bots cannot call the client API's contact import method, which Telegram documents as available to users only (contacts.importContacts).

Client API: automating a real Telegram account

The Telegram client API (MTProto) is what official and third-party apps use. Libraries such as TDLib, Telethon and Pyrogram wrap it, and most open-source "phone number checker" scripts are built on it.

Before building on it, note what Telegram documents in Obtaining api_id:

• You need an api_id and api_hash from my.telegram.org, created from an existing Telegram account; each phone number can be linked to only one api_id.
• Third-party clients must follow the API Terms of Service. Accounts using unofficial clients are placed under observation, and flooding or spamming through the API can lead to a permanent ban.
• Importing contacts stores them on the account that runs the code.

The client API is a good fit for building a genuine Telegram client or automating your own account. For checking business contact lists, it means company data sits in one person's account, and losing that account stops the workflow.

Registration check API: answering whether a number is on Telegram

A registration check API is built for job three. TG Validator's REST API works without any Telegram account on your side:

• Single check: POST /api/v1/check with an X-API-Key header carrying your sk_ prefixed key. The JSON body names the tg service type and the phone number in E.164 format.
• Small batches: POST /api/v1/batch-check accepts up to 100 numbers per request.
• Same-response flow: both endpoints return results in the response; there is no task to submit or poll.
• Response envelope: the documented envelope wraps each answer with a business code and a message. A completed result tells you, in the same response, whether the number you sent is registered on Telegram. A check that cannot be decided returns a non-zero business code and no completed result.
• Balance: GET /api/v1/balance lets your service check remaining balance before a large job.

The current API documentation describes per-user concurrency and timeout controls rather than a per-minute request limit: up to five in-flight checks, a 60-second timeout for a single check and 300 seconds for a multi-number check, with one multi-number check per account at a time. Confirm these in the documentation before tuning workers, since they can change.

For lists far beyond 100 numbers, the separate asynchronous bulk endpoints accept a TXT or CSV upload and return one result.csv when the task finishes.

Telegram phone number API comparison

Many products combine two of these: a bot to talk to users who opt in, and a registration check to decide which existing contacts to invite through Telegram at all.

Integration checklist for a registration check API

• Normalize first. Convert numbers to E.164 (plus sign, country code, no trunk prefix or punctuation) before calling the API.
• Keep the key server-side. Never ship it in a mobile app or browser bundle, and manage keys from the dashboard.
• Handle three outcomes. Yes, no and undecided. Store undecided checks separately and retry later instead of writing them as negatives.
• Respect concurrency. Size worker pools to the documented in-flight limit and back off on errors rather than retrying in a tight loop.
• Store the check time. Registration is a signal at check time; keep the date so stale results can be refreshed.
• Budget for decided checks. Every completed decided check is charged at the applicable rate whatever the answer, so deduplicate before sending.
• AI clients: an MCP endpoint at https://tgvalidator.com/mcp exposes the same-response checks and balance to MCP-compatible clients, using Bearer authentication with the same key and balance. Bulk tasks stay on the REST API.

FAQ

Can a Telegram bot look up a user by phone number?

No. A bot receives a phone number only when a user shares it, typically through a reply keyboard button that requests the contact in a private chat. Checking a list of numbers needs either a user account on the client API or a registration check API.

How can teams check Telegram registration without a Telegram account?

Use a registration check API. TG Validator accepts an E.164 number at POST /api/v1/check, or up to 100 numbers at POST /api/v1/batch-check, authenticated with an X-API-Key header, and returns the result in the same response.

Is there a per-minute rate limit on the TG Validator API?

No per-minute request limit is published. The documentation describes per-user concurrency and timeout controls instead, so integrations should size workers to those controls and check the current documentation for changes.

How can teams try the API before a larger rollout?

Registered users can contact support to receive 100 free checks, which is enough to test input normalization, undecided handling and logging against a small sample.

Learn More

Choose the product information that fits the next step in your workflow.

• View the product documentation →
• Talk to the team →