General description

The API is intended for current and potential Onlinesim partners. It allows you to monetize your numbers by providing them to our customers for receiving SMS from various services and applications.

Currently, two versions of the API are implemented:

v1 is suitable for partners who already have their own logic for working with numbers. In this scheme, our server contacts yours for information about available numbers and, if a suitable number is found, requests it to receive SMS.
v2 has a reverse scheme: the main logic of operations is on our side. You periodically send us a list of your numbers and forward incoming SMS to them, while the numbers are immediately available for order by customers.

v1 API

All interaction takes place via HTTP POST and/or GET requests between the endpoint specified by you and our support.

API v1

Requirements for v1:

Request / response format: JSON4
Encoding: UTF-8
Make sure that the user-agent is included in the request headers
All requests / responses use gzip compression
The names of countries and services used in the response of GET_SERVICES must match the corresponding lists of countries and services
One number should only be used for one operation at a time: your server can issue this same number for another service only after the previous operation is completed
It is necessary to implement functionality to exclude the issuance of numbers with certain masks: if an exclusion mask is specified in the request, numbers with such a sequence of digits should not be issued (for the GET_NUMBER request)
Webhook PUSH_SMS: your server must automatically forward SMS received by numbers with active operations to the Onlinesim server
Filtering can be performed either on our side or on yours. Before integration, inform us which option is preferable for you
The number must be issued within 10 seconds of receiving the GET_NUMBER (and GET_NUMBER (RENT)) request, otherwise the number order is canceled

Checklist for integration:

It is necessary to implement 3 methods and a webhook:

GET_SERVICES - requests the number of numbers by country and service from your server

GET_NUMBER - reserves a number for a short period (by default 15 minutes) with specified parameters for receiving SMS from a specific service for a specified amount

PUSH_SMS (webhook) - when an SMS is received by a reserved number, your server sends it to our server

FINISH_ACTIVATION - closes the operation with specific parameters (depending on the result)
Contact us via email or Telegram to create a partner profile, provide the URL for requests from our side, obtain a link for the webhook, and test the numbers.
After successful tests, your numbers will be available to our customers within a few hours.

v2 API

Reseller API v2 allows you to integrate your equipment and numbers for their subsequent use by customers for receiving SMS through our website. We have tried to make it as simple as possible for integration. To get started, you need to:

Implement 2 methods:

sendNumbersOnline - sends a list of your numbers to our server, this request should be sent every 5 minutes to update the list of numbers and as confirmation of your server's uptime;

If you plan to use a large number of numbers and sending sendNumbersOnline every 5 minutes as confirmation of uptime is difficult for you, we recommend using an alternative option - the checkWork request.
forwarding incoming SMS to our server — addMessage (one message at a time) or addMessages (in batches).

It is recommended to use addMessages instead of addMessage and send SMS in batches, for example, once every 5 seconds.

Contact support to obtain _SERVER_URL_
The remaining requests are optional, implementing them is not mandatory, but their description is available in the documentation.
The requests have an optional parameter test, which can be used for testing. It can take the values test1 and test2; if set to the first, it will allow the request to reach the server but will not trigger function execution. If set to test2, it will return the body of your request in the response. The parameter can be passed either in the query string (for GET methods) or as a field in its body (for POST methods) - both options are valid.

After you receive a response indicating that the sendNumbersOnline request was successfully executed, contact partner support to check if our server is receiving messages using the addMessage or addMessages requests. If successful, your numbers will be available to our customers within a few hours.

Appendix

Workflow

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

Contact

Email: partners@onlinesim.ru
URL: https://onlinesim.io

License

GNU General Public License, version 3.0

Servers

`{yourserver}`

Your server URL

Variables:

Name	Default	Enum	Description
`yourserver`	`https://{yourserver.com}`	---	---