The SMS Activate App REST API lets your code buy a private number, trigger a verification and read the SMS code, for your own apps, accounts and tests.
This guide covers the full flow: picking a number, buying it safely, reading the OTP (one-time password) code and releasing the number when you are done.
When to automate
Automation fits work you own and repeat. Three common cases:
- End-to-end tests of the SMS steps in your own app: sign-up, login, password reset and 2FA (two-factor authentication).
- Keeping 2FA working for your own service accounts and internal tools.
- A verification step inside a product you run.
Each number is a private virtual number. It is a real mobile or local number from a carrier's range, depending on the country. Your account holds it for a 28-day term. The same number can receive later codes, so re-verification and account recovery keep working during the term.
Two limits apply. A number is final and non-refundable once issued. The platform you verify with, not us, decides whether it accepts a number.
Most codes arrive within a few minutes of the platform sending them. We do not publish a delivery rate yet, so check a number with your target platform before you build a pipeline around it.
The API receives SMS. It does not send them.
Before you start
- Create a free account on the registration page.
- Add balance to the account.
- Create a personal API key in the account dashboard, on the API keys tab, or in the Telegram bot.
Send the key with every request, the catalog included:
The key spends your balance. Keep it server-side, in a secret store or a CI secret. Never put it in client code or commit it to a repository.
Reference details:
- Base URL: https://api.sms-activate.app/v1/public
- Money is integer USD cents. balanceCents: 2000 means $20.00.
- Machine-readable spec: the OpenAPI file (OpenAPI 3.1).
- Human-readable docs: the API docs.
- A ready skill for LLM agents: the agent skill.
- Limits: at least 120 requests a minute per account, and 30 purchases a minute. Over them the answer is rate_limited with a Retry-After header.
The verification flow
- Call GET /countries. It returns availability and the price range for each country.
- Call GET /numbers/search?country=US&limit=1 to pick a live number. Each result carries phoneNumber and your price in priceCents.
- Buy the number with POST /numbers and the body {"phone": "<phoneNumber>", "country": "US"}. Add an Idempotency-Key: <uuid> header, so a retry never charges you twice. A successful purchase returns 201 with number, chargedCents and balanceAfterCents. Two optional fields are available: autoRenew (default true) and note.
- Enter the number in the flow you are testing and trigger the SMS.
- Read the code. Poll GET /numbers/{id}/sms for that number, or GET /sms for all of them, roughly every 5 to 15 seconds, and set a timeout. Each SMS has id, numberId, from, to, body and receivedAt; take the code out of body. Feeds are cursor-paginated with cursor, limit and nextCursor.
- Finish. Send PATCH /numbers/{id} with {"autoRenew": false} to stop renewal, or DELETE /numbers/{id} to release the number. For a test suite you run every day, keeping one number on renewal is usually simpler than buying a new one each run.
Example in curl
The first call finds a number. The second buys it. The third reads incoming SMS.
Replace +15551234567 with a number returned by the first call. If you retry the purchase after a network error, reuse the same Idempotency-Key value instead of generating a new one.
Example in Python
This function waits for a code on one number you already own. It uses the requests library and reads the key from the environment.
If earlier SMS on the same number could match, compare receivedAt with the time your test triggered the message, and take only a newer one.
A webhook instead of polling
Send PATCH /numbers/{id} with {"forwardWebhookUrl": "https://your-app.example.com/sms"}, and every SMS and call on that number is posted to your server as it arrives. The address is checked first: it must answer a test POST with a 2xx status.
Each request carries x-vpn-event, x-vpn-timestamp and x-vpn-signature. The signature is HMAC-SHA256 of v1.<timestamp>.<raw body> with your webhook secret. Verify it on the raw bytes, and reject a timestamp more than five minutes off.
Polling is simpler for a test that runs once. A webhook suits a long-running service that handles codes as they come in.
Handle errors as answers
Every error has the same shape:
Branch on the error code, never on the HTTP status. One status can carry more than one refusal, so the status alone does not tell you what happened. Some refusals add a details object, for example requiredCents and availableCents on insufficient_balance.
Codes to handle:
- insufficient_balance: your balance does not cover the purchase. Stop and top up.
- no_numbers: no matching number is available right now. Pick another number or country.
- number_unavailable: the number was sold or is no longer for sale. Search again.
- validation_failed: the request body or parameters are wrong, or the purchase has no Idempotency-Key. Fix the input.
- idempotent_replay: a request with this Idempotency-Key came with another body or is still being processed. Do not treat it as a new purchase.
- rate_limited: too many requests. Wait as long as the Retry-After header says.
- priceexceeded and providerfailure: read message, show it and stop the run. After provider_failure, check your numbers before you buy again.
None of these is a defect to retry blindly. Show the error to the person running the code, or stop the run. Keep the reqId in your logs. Support uses it to find your request.
In a CI test suite
- Run SMS tests as a separate, serial job, so two tests never read the same code.
- Store the API key as a CI secret.
- Match each code to its test by the number and the time the test started.
- Set a timeout and fail with a clear message that names the number and the step.
- Keep one renewing number for repeated runs instead of buying a new one each time.
Useful videos
Third-party videos on the techniques this guide uses. They teach general techniques and do not cover our service.
- Python Requests Tutorial: Request Web Pages, Download Images, POST Data, Read JSON, and More (Corey Schafer): sends GET and POST requests from Python, with headers, and reads JSON answers.
- Server-Sent Events Crash Course (Hussein Nasser): how a Server-Sent Events stream works and when it beats polling.
- Polling vs Webhooks | System Design Tradeoffs (SoftwareDude): the cost and benefit of asking on a timer versus receiving a push.
- Idempotency in APIs Explained | Why It Matters + Code Example (Arkynate): idempotency keys and safe retries, with code.
- Playwright Tutorial: Re-use state & Re-use Authentication (CommitQuality): log in once in a test suite and reuse the signed-in state, so the SMS step runs only when it must.
Next steps
- Read the full reference in the API docs.
- Load the spec into your tools from the OpenAPI file.
- Give an LLM agent the ready agent skill.
- Check current prices on pricing.
- If you plan to build a product on top of the API, read the overview how to earn with virtual phone numbers.