Alternative API

v1.0

General 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.

getQiwiRequisites is accepted for compatibility and always answers {"status":false}.

Postman collection available here:

Run In Postman

Postman documentation

Answers

  • The HTTP status is always 200, errors come in the body.
  • Text answers (text/plain) are KEY: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 {}.
  • country is a country ID of the sms-activate numbering (id in getCountries, Russia is 0), not a dialing code. Without country the 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

License

GNU General Public License, version 3.0

Servers

https://onlinesim.io

Onlinesim server