You changed the base URL. Now what? A checklist for moving your bot to handler_api.php
If your bot already works with an sms-activate-style API, moving to our handler_api.php starts with a single line in your config: the base URL. There's one endpoint. Requests go via GET to the path /stubs/handler_api.php, and the method names are the ones you already know. The tricky part is the assumptions baked into your old integration: timeouts, polling frequency, country IDs, refund logic. Below is a checklist we recommend working through on a separate key while your production traffic still runs on the old setup.
Which methods are the same
Our sms-activate-compatible API covers the bot's core loop, getPrices → getNumber → getStatus → setStatus, plus the reference calls around it:
- getBalance: the balance of the account the key belongs to;
- getCountries and getServicesList: the lists of countries and services;
- getPrices: prices by service and country;
- getNumber: buying a number for a service;
- getStatus: the activation status and the code;
- setStatus: 3 to request another code, 6 to complete the activation, 8 to cancel.
If your bot calls other methods or sends other values to setStatus, find those places in the code before you switch over. Then check on staging what the bot does with the response.
What to check in your bot's logic
- Country and service codes. Don't carry IDs over from your old config blindly. Pull getCountries and getServicesList and compare them with what's hardcoded in the bot.
- The code wait timer. The activation window is set per service, currently one hour. With a single constant for every service, the bot will either drop an activation before its window ends or keep polling one that's already closed. Keep a separate timer for each service and verify the windows on staging.
- Cancellation. setStatus=8 doesn't go through during the first minute after purchase. If your bot cancels an order right away when something fails, add a retry after 60 seconds.
- Request budget. The limit is 600 requests per minute per key. The bot gets the code by polling getStatus, and that polling eats most of the limit. Thirty activations polled once a second add up to 1800 requests per minute, three times the limit. The same thirty polled once every five seconds come to 360, which leaves room for getPrices and getBalance.
- Refunds. If the code doesn't arrive before the window ends, the money comes back automatically. The same applies if you cancel before a code arrives. Refunds go only to your account's internal balance, not to a card or a wallet. Once the SMS has been received, the service counts as delivered, and that order isn't refunded. If you keep your own records of money per order, check them against these rules.
- Another code. After setStatus=3 the bot goes back to polling getStatus instead of closing the activation.
- Currency. Prices and balance are in US dollars. If your bot's config has price thresholds in another currency, convert them.
- Concurrent orders. Your limit depends on your account's reputation. The dashboard shows your current limit, how much of it is in use, and the share of orders that received a code over the past 7 days. A bot that grabs numbers "just in case" and then cancels them in bulk drags that share down.
softId for software owners
If you distribute your own software, you can connect it to our partner program. Applications are reviewed manually, usually within a day. Once approved, you get a software_id. Your software passes it in the softId parameter when it buys a number, and you as the owner earn 5% of the price of every activation your users make, with no cap. Users pay from their own accounts, and their price doesn't change. The parameter is optional: without it, the API works exactly the same.
Keys and a staging run
In the "API" section of the dashboard you can issue several named keys. We show the key string only once and store just its fingerprint, so put the key in your secrets store as soon as you issue it. If you lose a key, issue a new one and revoke the old one. The limit is counted per key, so staging tests don't take requests away from your production bot.
Run the steps in this order:
- getBalance: the key is accepted and the balance shows up. For steps 3 to 5 you need enough on the balance to cover at least two activations.
- getPrices: there's a price for each "service + country" pair you need.
- getNumber: a number is issued and the bot has saved the activation ID.
- getStatus: the bot polls at its production rate and stays within the limit.
- A second number: buy it, wait a minute, and send setStatus=8. The order amount should come back to your balance.
Each key in the dashboard shows the date it was last used. After the switch, this tells you that requests are coming from the production key and that the staging key has gone quiet and can be revoked.
Start in the "API" section of your dashboard. Issue a key with a name like "staging", run getBalance → getPrices → getNumber on it for your services and countries, and only then change the URL and key in your production config.