Onlinesim API

v1.1

General description

This API will allow you to access all services provided by Onlinesim:

  • SMS receiving from a single specific service on a virtual number;
  • rent a number to receive SMS from multiple different senders (apps/websites/mobile numbers);
  • you can also use our free numbers to test the service before the purchase.

List of API requests

Requests are specific for each service provided by Onlinesim and allocated in corresponding sections:

Profile section

These requests are related to the profile or all the services provided by Onlinesim:

  • getBalance - returns the current available balance of your profile, the frozen balance (the funds reserved for active operations, which will be returned if those operations are cancelled), and information about your referral program income.
  • webhook - allows you to set a URI to which all the messages from your active operations will be forwarded to. This includes messages from both single-service and long term rental.

Single-service activations section

Allows you to order a number to receive an unlimited number of SMS from a single service within a short time window (15 minutes for most of the services). Please note that you cannot change the service during the operation. To receive SMS from different services, you will need to order new numbers with the appropriate parameters.

  • getTariffs - returns a quantity of available numbers for each service and country (if specified);
  • getNum - orders a number for a particular service, allowing to receive SMS messages from it;
  • getState - returns detailed information on all active numbers of the profile (including received messages);
  • setOperationRevise - requests next received by the specified number SMS from the queue, if first one didn't have the right code and/or expected information;
  • setOperationOk - sets operation status as successful and closes the operation.

Rent section

This service implies that the number will be used to receive SMS from multiple different senders (including SMS from other mobile numbers), except for those that are prohibited.

  • tariffsRent - returns a list of countries with detailed information on rental plans;
  • getRentNum - orders a number of a chosen country for rent for a certain period;
  • extendRentState - extends the rent of a given number;
  • getRentState - returns a list of numbers of your profile with current active rent and received messages;
  • closeRentNum - closes the rental number.

Free numbers

This API allows you to access the functions to use free Onlinesim numbers available on the home page of our website.

You can use these numbers for testing, but please note that the quantity of available numbers as well as list of available countries are limited. It is also worth noting that messages received on free numbers are not private — they are displayed in the corresponding widget on the main page and are accessible to other users of the site.

There is one general request that allows you to access free numbers:

  • getFreeList - returns detailed information on available list of countries, free numbers and messages they've received.

Postman collection available here:

Run In Postman

Postman documentation

Each request has its own description, type, endpoint's URL, parameters, request and response schemas. Some responses can have examples of specific errors that might appear. Responses are represented in JSON or TXT format based on method called and results.

Exception Handling

Below are common errors: they are not tied to a specific endpoint and may occur in multiple methods. Such responses always come with HTTP status 200, and the error code is passed in the response field:

{
  "response": "ERROR_CODE"
}

Processing Rules

  1. Code format — UPPER_SNAKE_CASE
  2. The list of codes is not closed — it may be extended
  3. An unknown code should be treated as a generic error and logged for investigation
Code Category Description
UNDEFINED_COUNTRY Request parameters Invalid country parameter value. Available values are in the country list
UNDEFINED_DAYS Request parameters Invalid rental or extension period. Valid values are in the days object of the tariffsRent response for base rental periods, and in the extend object of the getRentState response for extensions
ERROR_NO_SERVICE Request parameters Invalid service parameter value. Available values are in the service list
NO_NUMBER State and availability No available numbers with the specified parameters. Retry later or try changing the order parameters (country and service for receiving, country and period for rent)
WARNING_LOW_BALANCE State and availability Insufficient balance to order a number
ACCOUNT_BLOCKED Account and access Account is blocked, contact support
API_ACCESS_DISABLED Account and access API access is disabled in the profile settings (the API Included toggle is inactive)
API_ACCESS_IP Account and access IP address is not in the allowlist (see Access from IP)
ERROR_WRONG_KEY Authorization Invalid API key
ERROR_NO_KEY Authorization API key is missing
INTERVAL_CONCURRENT_REQUESTS_ERROR Request limits Exceeded the allowed frequency or number of concurrent requests. Reduce the intensity of requests and try again later
REQUEST_NOT_FOUND Routing The method name is invalid or missing
TRY_AGAIN_LATER Other An unexpected error occurred, try the request again later

Terms of Service: https://onlinesim.io/documentation/offer

Contact

License

GNU General Public License, version 3.0

Servers

https://onlinesim.io

Onlinesim server