Manual SMS code retrieval is a bottleneck in any large-scale verification process. When you need to register 500 accounts or automatically process incoming OTP in production system, virtual number provider API becomes key tool. Let's examine integration architecture, typical scenarios, and practical code examples.

Basic Concepts of Virtual Number API

Two Operating Modes

Most API providers support two fundamentally different modes:

  • Polling (inquiry) — your application periodically requests SMS status. Simpler to implement, but creates delay and API load
  • Webhook (push) — provider itself sends HTTP request to your endpoint when SMS arrives. Instant, efficient, recommended for production

Phone Number Lifecycle Through API

  • GET /numbers/available — get list of available numbers by country/service
  • POST /numbers/activate — rent/activate number
  • GET /sms/{activation_id} — check incoming SMS (polling)
  • POST /numbers/{id}/status — confirm SMS receipt or cancel
  • DELETE /numbers/{id} — release number

Integration Example: Python + Polling

Basic script for receiving OTP code during service registration:

  • Request number for needed service (e.g., Instagram)
  • Pass number to website registration process
  • Poll every 5 seconds for 5 minutes
  • Extract code from SMS body with regex
  • Confirm receipt (so number doesn't charge twice)

Key activation request parameters:

ParameterTypeDescription countrystringCountry code: "us", "gb", "de", "ru" servicestringService identifier: "instagram", "google", "fb" operatorstring (optional)Specific operator: "att", "tmobile" forward_urlstring (optional)Webhook URL for push notifications

Webhook Integration Architecture

Interaction Scheme

Production architecture for high-load system:

  • Nginx receives webhook requests from provider on HTTPS endpoint
  • FastAPI/Express parses request body, checks Secret signature
  • Message placed in queue (Redis/RabbitMQ) for async processing
  • Worker extracts OTP code with regex, updates status in DB
  • Main registration process gets code via callback or Redis polling

Example Payload from Provider

Typical webhook request structure:

  • activation_id — activation ID in provider system
  • phone — phone number receiving SMS
  • from — sender (e.g., "GOOGLE" or "+18005551234")
  • text — full SMS text
  • created_at — Unix timestamp of receipt

Parallel Mass Registration

Architecture for 100+ Registrations Simultaneously

Naive approach — sequential registration — gives 1 account per minute. Parallel architecture:

ComponentTechnologyFunction Task QueueCelery / BullMQRegistration task queue Workers10–50 parallelEach conducts 1 registration API PoolRate limiter + retryControl provider limits SMS ListenerWebhook + Redis pub/subDistribute SMS to workers StoragePostgreSQL / MongoDBAccounts, statuses, logs

With 50 parallel workers and average registration time 3 minutes — 1000 accounts per 1 hour. Limiting factor: API provider rate limit and target site speed.

Error Handling and Retry Logic

Typical API Errors

  • SMS didn't arrive within timeout (5 min) — number needs cancellation and new request. Reason: service sent SMS to different number or operator delay
  • Number already used for this service — provider should control this, but sometimes misses. Detection: service says "this number already registered"
  • API rate limit — implement exponential backoff with jitter: 1s, 2s, 4s, 8s...
  • Temporary provider unavailability — circuit breaker pattern: after 3 consecutive errors wait 30 seconds before next attempt

Integration with Antidetect Browser via Playwright/Selenium

Full registration automation = number API + headless browser:

  • Python script requests number via API
  • Playwright opens browser with needed fingerprint and proxy
  • Fills registration form, inserts received number
  • Webhook or polling waits for SMS with code
  • Playwright enters code in verification form
  • Account saved in DB with login/password/number/proxy

Rate Limits and Best Practices

RecommendationWhy Important Cache available numbers list (TTL 60 sec)Reduces API load, speeds up work Verify webhook request signaturesProtection from fake SMS Log all SMS including unrecognizedHelps with debugging and disputes Don't hold activated number longer than 20 min without SMSAvoid charging for unused activations Use connection pooling for HTTP clientReduces latency with parallel requests

SDK and Ready Libraries

Most professional providers offer official SDKs for Python, Node.js, PHP, Go. This saves time writing HTTP wrappers and error handling. Check SDK availability when choosing provider — shows API maturity.

turbon.rent API documentation includes code examples in main languages, description of all endpoints and webhooks — enough for integration in several hours.

Virtual number API is not just convenience, it's difference between business scaling 100x and manual labor hitting performance ceiling.