API Documentation
Buy virtual numbers and check SMS codes programmatically. Every endpoint below has a live "Try it" tester that calls the real API with your key and shows you the exact response — the same thing you'd get from curl.
Authentication
Every request requires your personal api_key, found on your Profile page. All requests are simple GET requests.
https://www.foxlysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getBalance
Most actions respond with one plain-text line (e.g. ACCESS_BALANCE:12.5000). getPrices, getServicesList, and getCountriesList respond with JSON.
Live testing
Every "Try it" button on this page fires a real request to the live API using the key below. You are not logged in, so paste an API key manually to test. Endpoints that spend balance or affect real orders are clearly marked and will ask you to confirm first.
getBalance
Returns your current wallet balance. Read-only — safe to test.
https://www.foxlysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getBalance
Example response
ACCESS_BALANCE:12.5000
Try it live
Response will appear here.
getServicesList
Returns every active service and the code to use as service elsewhere. Read-only — safe to test.
https://www.foxlysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getServicesList
Example response (JSON)
[
{ "id": "wa", "name": "WhatsApp", "image": "https://yourdomain.com/assets/img/placeholder.png" },
{ "id": "tg", "name": "Telegram", "image": "https://yourdomain.com/assets/img/placeholder.png" }
]
Try it live
Response will appear here.
getCountriesList
Returns every active country, its ISO code, and its flag emoji. Read-only — safe to test.
https://www.foxlysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getCountriesList
Example response (JSON)
[
{ "id": "0", "name": "USA", "iso_code": "US", "emoji": "🇺🇸" },
{ "id": "36", "name": "Canada", "iso_code": "CA", "emoji": "🇨🇦" }
]
Try it live
Response will appear here.
getPrices
Live price (with markup already applied) and stock for a service/country pair. Always fetched fresh — never cached. Read-only — safe to test.
| service | Service code, from getServicesList |
| country | Country code, from getCountriesList (not our internal database ID) |
https://www.foxlysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getPrices&service=wa&country=187
Example response (JSON)
{ "187": { "wa": { "cost": 0.99, "count": 452 } } }
Try it live
Response will appear here.
getNumber
Purchases a virtual number at the current live price and debits your balance. Debits your real wallet balance — this is a real purchase, not a simulation.
https://www.foxlysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=wa&country=187
Example response
ACCESS_NUMBER:184:15551234567
Where 184 is your order ID (use for setStatus/getStatus) and the second value is the phone number.
Try it live
Clicking Send Request below will purchase a real number and debit your wallet. You'll be asked to confirm first.
Response will appear here.
setStatus
Cancel an order for an automatic refund. Affects a real order — only cancels/refunds when eligible.
| id | Order ID returned by getNumber |
| status | -1 or 8 = cancel & refund; 1/3/6 = acknowledged (no-op) |
https://www.foxlysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=setStatus&id=184&status=-1
Example response
ACCESS_CANCEL
A cancel request must wait at least 300 seconds after purchase before it's accepted — this gives the number a fair chance to receive a code first. If a code has already arrived, cancelling is rejected and the order completes normally instead.
Try it live
Response will appear here.
getStatus
Poll every few seconds to check whether a code has arrived. Read-only — safe to test.
https://www.foxlysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getStatus&id=184
| STATUS_WAIT_CODE | Still waiting |
| STATUS_OK:123456 | Code received |
| STATUS_CANCEL | Cancelled, expired, or refunded |
Try it live
Response will appear here.
Error codes
| BAD_KEY | Missing or invalid API key |
| BAD_ACTION | Unknown action |
| ACCOUNT_BLOCKED | Account suspended or banned |
| BAD_SERVICE | Unknown/inactive service or country code |
| NO_BALANCE | Insufficient wallet balance |
| NO_NUMBERS | No numbers available right now |
| NO_ACTIVATION | Order ID doesn't exist or isn't yours |
| BAD_STATUS | Invalid status value |