Onlinesim API
v1.1General 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 balance of your profile (frozen funds included), the frozen part (funds reserved for active operations, returned if those operations are cancelled), and your income from the affiliate program.
- 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.
- getProfile - returns the profile settings, including the defaults used by the API (country, rejected prefixes, webhook URL);
- profile.php - changes the profile settings, for example sets or clears the webhook URL;
- getPaymentHistory - returns the history of top-ups;
- webhook-logs - returns the log of webhook deliveries.
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);
- getNumbersStats - returns the prices and the stock of numbers by country and service;
- getPrice - returns the price of a number for a service in a country;
- 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:
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. Every answer is JSON.
Libraries
Official client libraries for this API. Each one includes a built-in mock for tests without network or balance.
| Language | Package | Documentation |
|---|---|---|
| JavaScript / TypeScript | npm onlinesim-js-api |
Docs |
| PHP | Composer s00d/onlinesim-api |
Docs |
| Python | PyPI onlinesimru |
Docs |
| Go | github.com/s00d/onlinesim-go-api/v3 |
Docs |
| Rust | crates.io onlinesim-rs-api |
Docs |
| Java | Maven ru.onlinesim:onlinesim-api |
Docs |
| Kotlin | Maven ru.onlinesim:onlinesim-kotlin |
Docs |
| C# / .NET | NuGet OnlineSim.Api |
Docs |
| Ruby | RubyGems onlinesim |
Docs |
| Dart / Flutter | pub.dev onlinesim |
Docs |
| Swift | SwiftPM https://github.com/s00d/onlinesim-swift-api |
Docs |
Errors
An error is a JSON object with the error code in response:
{
"response": "ERROR_CODE"
}Errors come with HTTP status 200, except two: 456 for an invalid API key or an expired OAuth token, and 429 when the request rate limit is exceeded. Each method lists the codes it can return; the codes below can come from any method.
Processing Rules
- Code format — UPPER_SNAKE_CASE (the only exception is the OAuth scope error below)
- The list of codes is not closed — it may be extended
- An unknown code should be treated as a generic error and logged for investigation
| Code | HTTP | Description |
|---|---|---|
ERROR_WRONG_KEY |
456 | Invalid API key or expired OAuth token. Also sent by public methods when an invalid key is passed |
ERROR_WRONG_KEY |
200 | No key in a request to a method that needs one |
ACCOUNT_BLOCKED |
200 | The account is blocked, contact support |
ACCOUNT_CLEANED |
200 | The account was deleted |
USER_NOT_ACTIVATED |
200 | The account email is not confirmed |
API_ACCESS_DISABLED |
200 | API access is disabled in the profile settings (the API Included toggle is inactive) |
API_ACCESS_IP |
200 | The IP address is not in the allowlist (see Access from IP) |
Invalid scope(s) provided: <scope> |
200 | The OAuth token was issued without the scope the method needs |
TRY_AGAIN_LATER |
429 | More than 400 requests per minute from one profile (from one IP for requests without a key), or more than 200 requests per minute from one profile to getNum, getPrice, getState and setOperationOk together |
TRY_AGAIN_LATER |
200 | Unexpected error, repeat the request later |
Terms of service:https://onlinesim.io/documentation/offer
Contact
- Email:support@onlinesim.io
- URL:https://onlinesim.io
License
Servers
https://onlinesim.io
Onlinesim server