Product guidance
Plan a Realtime Phone Verification API Workflow for Telegram
Design a Telegram phone verification API workflow on TG Validator's realtime endpoints: one number or up to 100 per synchronous request, E.164 formatting, and concurrency limits.
A technical guide to designing a realtime phone verification API workflow with TG Validator, covering the synchronous single and multi endpoints, concurrency limits, E.164 formatting, and signal interpretation.
A TG Validator verification workflow is built on realtime checks: submit one E.164 identifier to POST /api/v1/check, or up to 100 identifiers to the synchronous multi endpoint POST /api/v1/batch-check, and the completed registration results return in the initiating HTTP response. Control client-side concurrency according to the API documentation. For a whole list far beyond one realtime request, an asynchronous bulk task is also available as an add-on.
Understanding the Synchronous Verification Model
TG Validator's primary model is synchronous. Use POST /api/v1/check for one identifier or the synchronous multi endpoint POST /api/v1/batch-check for up to 100 identifiers; the completed results return in the same HTTP response, with no task submission, polling, callback, or download step, and no same-country requirement. As a fallback for a whole large list, an asynchronous bulk task (/api/v1/bulk-tasks) is also available: upload the file, receive a task id, then poll the task and download the result file when it finishes. You choose the country the numbers belong to when submitting a task, and the list should be essentially that one country. The rest of this guide focuses on the synchronous path.
Preparing Your Data for Verification
Before initiating requests, ensure all phone numbers in your dataset are formatted according to the E.164 international numbering plan. The API requires an X-API-Key header and a Content-Type: application/json header. Use POST /api/v1/check with service_type=tg and one E.164 identifier, or use the synchronous multi endpoint POST /api/v1/batch-check with service_type=tg and an identifiers array of up to 100 E.164 numbers. Because TG Validator is focused exclusively on Telegram, the service type must always be tg.
Architecting a Realtime Phone Verification API Workflow
Managing throughput is the most critical component of a realtime phone verification API workflow. The TG Validator API caps how many checks one account can have in flight at the same time, and the API documentation states the current ceiling. Your client-side application must throttle requests to stay within that boundary. If your system exceeds this threshold, the API will reject the requests. Concurrency-limit rejections are not charged and do not produce a check result, meaning your application should be designed to pause and retry these specific requests safely.
Interpreting the Registration Signal
The API returns a documented code, message, and data response envelope. Within this envelope, the Telegram registration status is located in the data.registered field. This result serves strictly as an account-presence signal at the time of the check. The product does not return avatar or business fields, keeping the payload focused entirely on the registration status.
Monitoring and Error Handling
Use the API response code to handle retryable failures; see the API documentation for the current error codes and limits.
FAQ
What should I do if I hit the concurrency limit?
The API allows each account only a limited number of concurrent checks, as stated in the API documentation. If you exceed it, the API rejects the request without charging your balance or producing a result. Your application should catch the concurrency error code, briefly pause, and retry the request.
Does a 'registered' status confirm that a user is reachable?
No. The registration signal only indicates Telegram account presence at the exact time of the check.
How should the workflow handle a list larger than one request?
Keep the synchronous multi endpoint as the primary path, up to 100 identifiers per request, within the documented concurrency limit. For a whole list far beyond that, an asynchronous bulk task is also available (upload, wait, download); you choose the country the numbers belong to when submitting, the list should be essentially that one country, and per-product minimum and maximum counts are listed in the API documentation.
How are failed checks handled in terms of billing?
Failed, timed-out, and undetermined checks do not retain the charge. See the pricing page for current plan and balance details.