Alternative API
v1.0General description
Alternative API is compatible with the sms-activate protocol: programs written for it work with Onlinesim after
changing the address to https://onlinesim.io/stubs/handler_api.php. Every method is one GET request to this
address; the action parameter selects the method:
https://onlinesim.io/stubs/handler_api.php?action=getBalance&api_key={api_key}It gives access to two services of Onlinesim: receiving SMS from one service (single-service activations) and renting numbers to receive SMS from any senders.
List of API requests
Profile section
- getBalance - returns the balance of your profile;
- getCountries - returns the list of countries and their IDs.
Single-service activations section
A number receives SMS from one service within a short time window (15 minutes for most services). The service cannot be changed during the operation: order a new number for another service.
- getNumbersStatus - the number of available numbers by service in a country;
- getNumber - orders a number of a chosen country and service;
- getStatus - returns the code from the received SMS;
- getFullSms - returns the full text of the received SMS;
- setStatus - asks for the next SMS or closes the operation.
Rent section
A rented number receives SMS from any senders (including other mobile numbers), except prohibited ones.
- getRentServicesAndCountries - countries available for rent, the number of free numbers and the price;
- getRentNumber - rents a number of a chosen country;
- getRentList - returns your active rentals;
- getRentStatus - returns the SMS received by a rented number;
- setRentStatus - closes the rent.
getQiwiRequisites is accepted for compatibility and always answers {"status":false}.
Postman collection available here:
Answers
- The HTTP status is always
200, errors come in the body. - Text answers (
text/plain) areKEY:value(ACCESS_BALANCE:12.34) or a single code (BAD_KEY). - JSON errors are
{"status":"error","message":"<CODE>"}. Errors that every action can give (BAD_KEY,BANNED,BAD_ACTION, the limit) are text even in JSON actions. - Lists in JSON answers come as objects with the keys
"0","1", …; an empty list is{}. countryis a country ID of the sms-activate numbering (idin getCountries, Russia is0), not a dialing code. Withoutcountrythe country is Russia.
Authorization
The API key goes in the api_key query parameter (the sms-activate name), or in apikey or key, or in the
Authorization: Bearer header — the API key or an OAuth access token. When several are sent, the first one in
this order is used. A wrong or missing key in api_key gives BAD_KEY. A wrong key in apikey, key or
Authorization is rejected before the method runs: HTTP 456 with {"response":"ERROR_WRONG_KEY"}.
Limits and caching
- getNumber, getRentNumber, setStatus and setRentStatus are limited to 3 requests per second and 150 requests per
30 seconds for one key (for one IP without a key). Over the limit the answer is the text
Too many requests. Please wait a moment before trying again.(HTTP 200). Reading actions (status polling, lists) have no limit of their own. - The site itself allows 400 requests per minute: over it the answer is HTTP
429. - The answers of reading actions (getBalance, getCountries, getNumbersStatus, getRentServicesAndCountries, getRentList, getRentStatus) are cached for 5 seconds: the same request (same parameters and key) repeated sooner gets the same answer, errors included. getStatus and getFullSms are not cached here, but the operation state behind them is cached by the Onlinesim API for up to 5 seconds (a new SMS can show up with that delay; setStatus=3 shows the next SMS at once). Actions that change something (getNumber, setStatus, getRentNumber, setRentStatus) are never cached.
Common errors
| Text answer | Description |
|---|---|
BAD_KEY |
The API key is wrong or missing |
BANNED |
The account is blocked |
BAD_ACTION |
Unknown action, or an error without its own code (for example a temporary error or too many concurrent requests) |
Too many requests. Please wait a moment before trying again. |
The converter's rate limit |
Codes of each method are listed on its page.
Terms of service:https://onlinesim.io/documentation/offer
Contact
- Name: Artem
- Email:support@onlinesim.io
- URL:https://onlinesim.io
License
Servers
https://onlinesim.io
Onlinesim server