Getting Started with the SMSTwins Simple API

Not every integration needs full REST JSON workflows. The SMSTwins Simple API at /v1/simple offers query-parameter actions with human-readable response codes — ideal for shell scripts, quick QA repro steps, and lightweight automation where brevity matters.

Authentication

Authenticate with sk_live_ API keys passed as query parameters or headers per documentation. Use separate keys per environment to respect tiered rate limits on free and paid plans.

Never commit keys to repositories; load from environment variables or secrets managers.

Available actions

balance

Returns current account balance with responses like SMSTWINS_OK:BALANCE followed by the numeric amount. Quick pre-flight check before batch activations.

request_number

Request an activation by specifying service and country codes. Success returns SMSTWINS_OK:NUMBER with the assigned non-VoIP line. Balance holds apply until SMS arrives, activation completes, or automatic refund triggers on timeout.

check_status

Poll activation state and retrieve parsed OTP when SMS arrived. Response codes indicate waiting, received, completed, expired, or cancelled states clearly for script branching.

cancel_number

Release an activation during the waiting window and refund held balance. Use when switching countries or abandoning failed attempts.

list_prices

Browse service and country pricing before purchasing — helpful for CI budget planning across 180+ countries.

Response code philosophy

Branded codes like SMSTWINS_OK:* and error prefixes make shell pipelines readable without JSON parsing. grep-friendly output accelerates manual developer workflows.

For complex applications, pair Simple API scripts with full REST and webhooks as you mature.

Example workflow

1. list_prices — confirm Telegram US cost
2. request_number — assign line
3. Trigger SMS from app under test
4. Loop check_status until OTP appears or timeout
5. cancel_number if aborting

Prefer webhooks over tight polling loops in production harnesses.

When to choose Simple API versus REST

Non-VoIP and refunds

Simple API actions use the same provider network as REST — non-VoIP SIM inventory with quality scoring. Timeout automatic refunds apply identically; check_status shows expired state when holds release.

Migration path

Teams often start with Simple API during prototyping, then adopt REST plus signed webhooks for scalable QA. Legacy handler compatibility eases transitions from other SMS verification providers.

The SMSTwins Simple API lowers the floor for developer access — readable codes, core activation lifecycle, and the same reliable SMS verification infrastructure powering enterprise integrations.