Developer API

Buy numbers and read codes from your own code

SwiftSMS speaks the SMS-Activate protocol, so the bots, farm managers and SDKs you already use work here by changing one URL and one key. Same wallet, same prices and the same automatic refunds as the app.

Get your API key Browse actions

Quick start

Every request is a GET (or a form POST) to one endpoint, with your key and an action. Buy a number, poll its status until the code lands, then mark it finished.

Your key lives under Account settings → Developer. Treat it like a password: it can spend your balance. It cannot change your password, delete the account or make payments.

Moving from another SMS-Activate-compatible provider? Replace its base URL with https://api.swiftsms.net — the path /stubs/handler_api.php is the same.

# 1. buy a WhatsApp number in the UK (country 16)
curl "https://api.swiftsms.net/stubs/handler_api.php?api_key=$KEY&action=getNumber&service=wa&country=16"
ACCESS_NUMBER:634357446:447882715800

# 2. poll until the code arrives
curl "https://api.swiftsms.net/stubs/handler_api.php?api_key=$KEY&action=getStatus&id=634357446"
STATUS_OK:852508

# 3. finish (or status=8 to cancel and refund)
curl "https://api.swiftsms.net/stubs/handler_api.php?api_key=$KEY&action=setStatus&id=634357446&status=6"
ACCESS_ACTIVATION

Actions

Endpoint https://api.swiftsms.net/stubs/handler_api.php · parameter api_key on every call.

getBalance

params: —

Your wallet balance, in euros.

Success: ACCESS_BALANCE:12.34
Errors: BAD_KEY

getNumber

params: service, country, maxPrice?

Buys a number. The wallet is charged now and refunded automatically if no code arrives.

Success: ACCESS_NUMBER:634357446:447882715800
Errors: NO_NUMBERS · NO_BALANCE · WRONG_MAX_PRICE:0.80 · BAD_SERVICE · BAD_COUNTRY

getNumberV2

params: service, country, maxPrice?

The same purchase, answered as JSON with the price and time.

Success: {"activationId":634357446,"phoneNumber":"447882715800","activationCost":0.8,"currency":978,…}
Errors: as getNumber

getStatus

params: id

Poll every 5 seconds or so; codes are fetched from the network continuously on our side.

Success: STATUS_WAIT_CODE · STATUS_OK:852508 · STATUS_WAIT_RETRY:852508 · STATUS_CANCEL
Errors: NO_ACTIVATION

getStatusV2

params: id

Includes the full text of the SMS.

Success: {"verificationType":0,"sms":{"dateTime":"…","code":"852508","text":"Your code is 852508"}}
Errors: {"error":"NO_ACTIVATION"}

setStatus

params: id, status

1 = number used · 3 = wait for another code · 6 = finish · 8 = cancel and refund (only before a code arrives).

Success: ACCESS_READY · ACCESS_RETRY_GET · ACCESS_ACTIVATION · ACCESS_CANCEL
Errors: NO_ACTIVATION · BAD_STATUS

getPrices

params: service?, country?

Prices in euros, keyed by country id then service code. Pass a service for its complete country list.

Success: {"16":{"wa":{"cost":0.8,"count":204663}}}
Errors: BAD_SERVICE · BAD_COUNTRY

getServicesList

params: —

Success: {"status":"success","services":[{"code":"wa","name":"WhatsApp"},…]}
Errors: —

getCountries

params: —

Success: {"16":{"id":16,"eng":"United Kingdom","iso":"GB","visible":1},…}
Errors: —

getActiveActivations

params: —

Numbers still waiting for, or holding, a code.

Success: {"status":"success","activeActivations":[…]}
Errors: —

Any action can also answer NO_KEY, BAD_KEY, BAD_ACTION or ERROR_LIMIT.

Prefer JSON? The REST API

The same key works on the REST API the SwiftSMS apps use, in an X-API-Key header: buy with POST /v1/activations, read with GET /v1/activations/{id}, cancel or ask for another code, and check GET /v1/wallet. Prices and countries are public at GET /v1/services.

curl -X POST https://api.swiftsms.net/v1/activations \
  -H "X-API-Key: $KEY" -H "content-type: application/json" \
  -d '{"serviceId":"wa","countryCode":"GB"}'

curl https://api.swiftsms.net/v1/activations/<id> -H "X-API-Key: $KEY"

Questions, answered

Is the SwiftSMS API compatible with SMS-Activate?

Yes. SwiftSMS answers SMS-Activate's handler_api.php actions — getNumber, getStatus, setStatus, getBalance, getPrices and the V2 variants — with the same response tokens. Software written for SMS-Activate or its successors works after you change the base URL to api.swiftsms.net and use your SwiftSMS API key.

Where do I find my API key?

Sign in, open Account settings, and find the Developer section. The key can be revealed and regenerated there; regenerating immediately disables the old one.

What currency are prices and the balance in?

Euros. getBalance returns your SwiftSMS wallet balance and getPrices returns our sell prices, which are exactly what a purchase debits.

Am I charged if the SMS never arrives?

No. The price is held when you buy the number and refunded automatically if no code arrives within about ten minutes, or immediately if you cancel with setStatus 8 before a code comes in.

Which country codes does the API use?

The numeric country ids used across the SMS-Activate ecosystem — 16 for the United Kingdom, 187 for the United States, and so on. getCountries returns the full list with ISO codes. An ISO alpha-2 code such as GB is accepted too.

Is there a rate limit?

1,200 requests per minute per account, which comfortably covers polling hundreds of numbers at once. Past it the API answers ERROR_LIMIT until the minute rolls over.

Your API key is already waiting

Every SwiftSMS account has one. Sign in, top up, and point your tools at api.swiftsms.net.

Open my account

No SIM, no contract — pay only when the code lands.