Reseller API

1.0

General description

This API allows you to provide us with numbers for SMS activations and turn your SIM cards into profitable assets by forwarding SMS codes from different websites and apps. We currently have 2 versions of API with two different approaches:

  • v1 is designed for requesting numbers with specific parameters from your server;
  • v2 is designed to accept from your server a list of numbers that can be purchased by our clients for various services

We're chargning clients per operation, not per SMS. Funds are credited upon successful completion of operation. Operations can lasts from 15 minutes (for single-service activations) to several month (for long term rental) during which clients can receive several SMS. Please note, that by proceeding you comply with these terms!

Both APIs requires Onlinesim partner account! You will need to register Onlinesim profile and contact partner support to get access to these APIs. Several methods of authentication are available (Authentication).

SMS filtering for both API can be done either on our side or yours. Before integration, please inform partner support which option you prefer. SMS filtration implies checking SMS you're sending to our server according to the patterns of the ordered service. It is necessary to prevent unscrupulous clients to use your numbers for SMS receiving from service with high cost while ordering cheaper ones. By default the SMS filtering is done on our side.

v1 API

Connection and configuration are specific for each individual partner, so you need to contact our tech support to get the details of integration. All interaction between our servers is happening as a series of POST and/or GET requests on agreed endpoints via HTTP.

API v1

This API will also require to implement number exception functionality on your side!

Requirements for v1:

  1. Requests and responses come in JSON4 format
  2. Encode scheme: UTF-8
  3. Make sure that user-agent is included in request headers
  4. All requests / responses use gzip compression method
  5. All country and service names in the GET_SERVICES response must use values from the corresponding lists of countries and services
  6. Each number can be used for one operation simultaneously: your server can issue the same number for other service only after the previous operation is completed
  7. You need to implement number exception functionality: if requested, numbers with certain sequence of digits (mask) should not be issued for GET_NUMBER request
  8. Webhook PUSH_SMS: your server have to forward to OnlineSIM server any SMS received by numbers with active operations as soon as they get them
  9. Filtering and spam checking can be done either on our side or yours. Please let us know which flow is preferable for your before the integration
  10. Response for GET_NUBMER (or GET_NUMBER (RENT)) should be sent within 10 seconds, otherwise the order will be cancelled

Integration checklist:

  1. Create 3 methods and a webhook:

    GET_SERVICES requests from your server amount of available numbers by country and service

    GET_NUMBER reserves a number for 15 minutes with specific parameters for SMS receiving

    PUSH_SMS (webhook) - once a reserved number receives a message, your server should forward it to us

    FINISH_ACTIVATION closes operation with specified parameters (based on the result)

  2. Contact us via email or Telegram to create a partner profile, provide endpoint URL on your server and receive one from us. Our support specialists will also run a few tests to make sure everything is working as expected.

  3. If tests are successful, your numbers will become available for our clients in a few hours.

v2 API

Reseller API v2 allows you to integrate your device with our website. It will allow your numbers to be purchased by our clients for SMS activations. We tried to make it as simple as possible, you only need to follow steps below:

  1. Create 2 methods:

  • sendNumbersOnline - sends a list of numbers that you want to provide us with. This request should be sent every 5 minutes to update a list and to confirm that your server is online;

    If you have a large quantity of numbers and sending sendNumbersOnline request every 5 minutes as uptime confirmation is not suitable for you, you can use alternative option - checkWork request.

  • addMessage - forwards SMS from your server to ours.

  1. Contact tech support to get _SERVER_URL_.
  2. Other requests are optional, you may never need it, but their description is available in the documentation.
  3. Requests have optional parameter test that can be used for testing purposes. It's value can be either test1 or test2, while being equal to test1, it will allow the request to be passed, however the data won't be saved by our server (the function will not be executed by this request), if it's value is test2 it will print out your request's payload in response.

When request sendNumbersOnline will be executed successfully, please contact partner support specialists, so they can test if your messages are forwarded correctly with addMessage request. When we confirm that everything is working as intended, we will add your numbers to the pool, and they will be available for purchase in a few hours.

Attachments

Workflow workflow

Servers