Product guidance
Plan a Bulk Phone Verification API Workflow
Learn how to design a bulk phone verification API workflow using TG Validator. Manage rate limits, format E.164 numbers, and process synchronous checks.
A technical guide to designing a synchronous bulk phone verification API workflow with TG Validator, covering rate limits, E.164 formatting, and signal interpretation.
To implement a bulk phone verification API workflow with TG Validator, design your application to process phone numbers synchronously while respecting the 200-requests-per-minute rate limit and the 3-concurrent-check limit. By submitting E.164 formatted numbers to the API, you receive a same-response registration status signal that informs your internal review processes without requiring complex batch infrastructure.
Understanding the Synchronous Verification Model
TG Validator operates exclusively on a synchronous request-response model for Telegram registration checks. Instead of uploading a file for asynchronous batch processing, your application sends a single request and receives a single result within the same HTTP response cycle. This architecture requires client-side logic to iterate through contact lists, sending individual checks sequentially or with controlled concurrency.
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 a POST /api/v1/check request containing an X-API-Key header and a Content-Type: application/json header. The JSON body must specify the service type as tg and include the E.164 number as the identifier. Because TG Validator is a single-platform product focused exclusively on Telegram, the service type must always be set to tg.
Architecting a Bulk Phone Verification API Workflow
Managing throughput is the most critical component of a bulk phone verification API workflow. The TG Validator API enforces a strict 200-requests-per-minute rate limit and allows a maximum of 3 concurrent checks per user. Your client-side application must throttle requests to stay within these boundaries. If your system exceeds these thresholds, the API will reject the requests. Rate and 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
Operational oversight is supported through the TG Validator dashboard, which provides visibility into API keys, check history, usage reports, recent checks, balance spend, and 7-day trends. When designing your error-handling logic, account for specific API error codes such as invalid JSON bodies, invalid phone numbers, missing API keys, insufficient balance, or validation service maintenance. Billing operates on a pay-per-check model, and any failed or undetermined checks are refunded automatically. For testing your initial integration, new accounts can contact support to claim a $0.10 trial balance.
FAQ
How does the synchronous nature of the API affect bulk processing?
Bulk processing must be managed client-side by iterating through records and sending individual requests while adhering to concurrency and rate limits.
What should I do if I hit the concurrency limit?
The API allows a maximum of 3 concurrent checks. If you exceed this, 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 are failed checks handled in terms of billing?
TG Validator uses a pay-per-check billing model. If a check fails or returns an undetermined result, the cost is automatically refunded to your account balance.