API Documentation - SMSBower
API SMS Activation Temporary mail Partnership Referral program
Registration Sign In
API
For clients For partners Temporary mail Other
API Documentation
Brief description of the API protocol logic
Method for requesting the number of phone numbers available GET_SERVICES
Request number method GET_NUMBER
SMS delivery method to the SMSBOWER server – PUSH_SMS
Request method to finish activation FINISH_ACTIVATION
Protocol testing
Status tables
Data tables

Brief description of the API protocol logic

The partner protocol is designed to provide phone numbers and incoming SMS messages via API directly to the SMSBOWER server.

All requests include the parameter - KEY. This key is provided by support staff and is available in the personal account.

Quantity requests GET_SERVICES, number requests GET_NUMBER and activation completion

FINISH_ACTIVATION are sent directly from our server to the partner's server.

Format URL — https://SMSBOWER where SMSBOWER can be partner.ru:port/SMSBOWER or partner.ru/SMSBOWER.php

GET_SERVICES
GET_NUMBER
PUSH_SMS
FINISH_ACTIVATION
The SMSBOWER server sends a request for quantity of phone numbers using the GET_SERVICES approximately every 10-20 seconds.
If you provide a count > 0 in response, you will receive a request for phone number issuance using the method GET_NUMBER
After receiving the GET_NUMBER request, you are required to provide a phone number that meets all criteria and forward all incoming SMS messages to us using the PUSH_SMS. This is necessary for us to perform clear and objective filtering and deliver the relevant SMS messages to the right service for our clients.
Upon completing all necessary tasks related to the phone numbers, you will receive a status 3 through the method FINISH_ACTIVATION. This status indicates that the phone number was successfully registered, and you have been rewarded for it.

Requirements

  • Request/response format: JSON
  • UTF-8 encoding
  • Always use a user-agent header in requests to the SMSBOWER server
  • Apply gzip compression method to all requests/responses

Field types:

  • int - integer value
    in the range from -2 147 483 648 to 2 147 483 647
  • Uint - unsigned integer value
    in the range from 0 to 2 147 483 647
  • long - integer value
    in the range from -9 223 372 036 854 775 808 to 9 223 372 036 854 775 807
  • Ulong - unsigned long integer value
    in the range from 0 to 9 223 372 036 854 775 807
  • cur - real value containing up to 2 decimal
    places, for example, 177.77;
  • boolean - literal values true or false
  • string - string value of unlimited length

Method for requesting the number of phone numbers available GET SERVICES

This request provides us with information about the quantity of phone number for services available for sale.

The POST request is transmitted from the SMSBOWER server to the partner's server.

! Please note: If your GSM modem is limited in the number of concurrently active modules, you should provide a count equal to the number of active modules.

Request fields
Field Type Required Description
action String GET_SERVICES
key String Protocol key
Answer fields
Field Type Required Description
status String Status of the response (see Status tables)
countryList Array List of countries
CountryList
Field Type Required Description
country String Status of the response (see Status Table)
operatorMap* Associative array Key - operator (see Data tables), value - associative array of services**
Example of a request
{
     "action": "GET_SERVICES",
     "key": "qwerty123"
}
Example of an answer
{
     "countryList":
     [
          {
              "country": "russia",
               "operatorMap":
               {
                    "beeline":
                    {
                         "ok": 15,
                         "wa": 20
                    },
                    "megafon":
                    {
                         "vk": 3,
                         "ok": 10
                    }
               }
          },
          {
               "country": "ukraine",
               "operatorMap":
               {
                    "life":
                    {
                         "vk": 0,
                         "wa": 32
                    }
               }
          }
     ],
     "status": "SUCCESS"
}

Number request method GET_NUMBER

This request provides us with a phone number that we pass on to the client.

The POST request is transmitted from the SMSBOWER server to the partner's server.

If the exceptionPhoneSet array contains a list of prefixes, for example 44742 and 44740, you should not provide a number that starts with any of these prefixes. The number of digits is not limited by the size of the prefix.

Request fields
Field Type Required Description
action String GET_NUMBER
key String Data Table
country String Data Table
service String Data Table
operator String Protocol key
sum Cur The amount you will receive for a successfully registered service
exceptionPhoneSet Array List of prefixes that are PROHIBITED
Answer fields
Field Type Required Description
status String Status of the response (see Status tables)
number Ulong Phone number with country code
activationId Ulong Activation ID in the partner's system
Example of a request
{
     "action": "GET_NUMBER",
     "key": "qwerty123",
     "country": "russia",
     "operator": "beeline",
     "service": "tg",
     "sum": "20.00"
}
Example of an answer
{
      "number": "79156537788",
      "activationId": "36532",
      "status": "SUCCESS"
}
Example of a request
{
      "action": "GET_NUMBER",
      "key": "qwerty123",
      "country": "russia",
      "operator": "any",
      "service": "vk",
      "sum": "10",
      "exceptionPhoneSet":
      [
          "7918",
          "79281",
      ]
}

SMS delivery method to the SMSBOWER server PUSH_SMS

This POST request is sent from the partner's server to the SMSBOWER server at the address: https://smsbower.online/agent/api/sms

If you receive a response with the status SUCCESS, mark the SMS as successfully delivered in your database and do not send it again. If a status other than SUCCESS is returned, repeat the request with a 10- second delay until you receive a SUCCESS status.

Example of a request
Field Type Required Description
action String PUSH_SMS
key String Protocol key
smsId Ulong ID of the SMS in the partner's system
phone Ulong Phone number (including the country code) to which the SMS was sent
phoneFrom String The sender's name (may be either alphanumeric or numeric) which sent the SMS
text String SMS text
Answer fields
Field Type Required Description
status String Status of the response (see Status tables)
Example of a request
{
     "action": "PUSH_SMS",
     "key": "qwerty123",
     "smsId": 1,
     "phone": 447472190082,
     "phoneFrom": "Microsoft",
     "text": "Microsoft access code: 5015"
}
Answer fields
{
      "status": "SUCCESS"
}

Request method to finish activation FINISH_ACTIVATION

This request is transmitted from the SMSBOWER server to the partner's server to complete activation.

POST request initiated from the SMSBOWER to the partner's server.

Activation management is fully controlled by SMSBOWER. Due to factors beyond our control, we may not receive a response from you regarding a successful status change. Therefore, if SMSBOWER sends a repeat activation completion request, you should check for the existence of the activation ID on your end. If the activation exists, send a status of SUCCESS in response.

Request fields
Field Type Required Description
action String FINISH_ACTIVATION
key String Protocol key
activationId Ulong Activation ID obtained in the second request
status Unit Status of the response (see Status tables)
Answer fields
Field Type Required Description
status String Status of the response (see Status tables)
Example of a request
{
     "action": "FINISH_ACTIVATION",
     "key": "qwerty123",
     "activationId": 100,
     "status": 3,
}
Example of an answer
{
      "status": "SUCCESS"
}

Protocol testing

After implementing the protocol, you need to contact our technical support team, provide the URL, and our staff will conduct testing. If the verification passes all parameters successfully, you will be successfully connected to SMSBOWER.

Simultaneous Number Issuance

You should handle simultaneous requests properly and not issue numbers repeatedly. For example, if you have 100 numbers for Telegram United Kingdom, and SMSBOWER simultaneously makes 100 requests for Telegram United Kingdom, the partner server should provide 100 unique numbers. If a number is issued multiple times, the test fails.

Correct Activation Completion

The change in activation status is fully controlled by SMSBOWER. The partner server should not autonomously complete activations.

SMS Delivery Verification

Once you receive an SMS, you must immediately forward it to the SMSBOWER server. If you receive a status of SUCCESS, you should not forward the SMS again. However, if you receive a different status, you should retry the request every 10-20 seconds. If an SMS is issued again after receiving a SUCCESS status, the test fails.

Field Type Verification

Thoroughly check the field types, specified in this documentation. If this condition is violated, the testing fails.

Country Code in Phone Number

Phone number issuance should be in digital format and include the country code.

Number Issuance Time Verification

You must issue numbers with a delay of less than 3 seconds. If it takes more than 3 seconds, the testing fails.

Number Quantity Verification

If you issue 1000 numbers in a request for quantity of numbers, but only 100 are issued at the same time, then testing has failed.

Exception Handling Verification

If you incorrectly handle exceptions for issuing a number, then testing has failed.

Response status
Status Description
SUCCESS The request was finished successfully
ERROR Error during request execution. The ERROR field should be filled with a description
NO_NUMBER No numbers are available. This response is only returned for a request number.
Activation status
Status Description
1 Issuing a number for this service is prohibited
3 Activation was successfully sold. You have received a reward
4 Activation was canceled*
5 Activation has been returned. The customer has been refunded for the activation. It's possible that this number was previously registered, and two-factor authentication may be enabled on the number

* The mechanism for cancellation works as follows: If a phone number has been canceled 5 times, you should not issue the same number again. It's possible that the number was not suitable for the client or was already registered for the specific service.

Successful answer to the request
{
     "status": "SUCCESS",
     //Information
}
Answer in case of an error
{
      "status": "ERROR",
      "error": "Description of the error"
}

Data tables

List of countries

The full list of countries with names and IDs can be found at the link https://smsbower.net/api#countries.

List of operators

At the moment, the breakdown by operators is under development, so you should pass the value any. Once this functionality is implemented, we will notify you through the technical support chat.

List of services

The full list of services with names and IDs can be found at the link https://smsbower.net/api#services

Write to us
I agree with the privacy policy and use of the requested data