Partner API Documentation
SMSBOWER
Version from 05.09.2023
Description of the protocol's operation
● 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 requests
(FINISH_ACTIVATION) are sent directly from our server to the partner's server.
● URL FORMAT :
[Link]
where SMSBOWER can be [Link]:port/SMSBOWER or [Link]/[Link]
GET_SERVICES GET_NUMBER PUSH_SMS FINISH_ACTIVATION
Description of the protocol's operation
The SMSBOWER server sends a request for quantity of phone numbers
using the GET_SERVICES method approximately every 10-20 seconds.
If you provide a count > 0 in response, you will receive a request for phone
number issuance using the GET_NUMBER method.
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 method. 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 FINISH_ACTIVATION method. This
status indicates that the phone number was successfully registered, and
you have been rewarded for it.
Description of the protocol's operation
● 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.
1. GET_SERVICES number request method
● Request fields:
Field Type Required Description ● This request provides us with information about
the quantity of phone number for services available
action string ü GET_SERVICES
for sale.
key string ü Protocol key
● The POST request is transmitted from the
SMSBOWER server to the partner's server.
● Answer fields:
● ! Please note: If your GSM modem is limited in the
Field Type Required Description number of concurrently active modules, you should
Status of the response (see Status provide a count equal to the number of active
status string ü
Table) modules.
countryList array ü List of countries
● countryList
* You should not send empty data arrays in the
Field Type Required Description operatorMap.
country string ü see Data Table ** Associative array of services: Key - a brief
Key - operator (see Data service name (see Data Table), value - the
Associative Table), quantity of phone numbers available for the
operatorMap* ü
array value - associative array of service (type: int).
services**
1. GET_SERVICES number request method
● Example of a request: ● Example of an answer:
{
"countryList":
{ [
"action": "GET_SERVICES", {
"country": "russia",
"key": "qwerty123" "operatorMap":
} {
"beeline":
{
"ok": 15,
"wa": 20
},
"megafon":
{
"vk": 3,
"ok": 10
}
}
},
{
"country": "ukraine",
"operatorMap":
{
"life":
{
"vk": 0,
"wa": 32
}
}
}
],
"status": "SUCCESS"
}
2. GET_NUMBER number request method
● Request fields:
Field Type Required Description
• This request provides us with a phone
action string ü GET_NUMBER number that we pass on to the client.
key string ü Protocol key • The POST request is transmitted from the
country string ü see Data Table SMSBOWER server to the partner's server.
service string ü see Data Table • If the exceptionPhoneSet array contains a
operator string ü see Data Table list of prefixes, for example 44742 and 44740,
The amount you will receive for a you should not provide a number that starts
sum cur ü
successfully registered service with any of these prefixes. The number of
exceptionPhone List of prefixes that are PROHIBITED to digits is not limited by the size of the prefix.
array ❌
Set give when requesting a phone number
● Answer fields:
Field Type Required Description
status string ü see Status Table
number Ulong ü Phone number with country code
activationId Ulong ü Activation ID in the partner's system
2. GET_NUMBER number request method
● Example of a request: ● Example of a request with exceptionPhoneSet:
{ {
"action": "GET_NUMBER", "action": "GET_NUMBER",
"key": "qwerty123" , "key": "qwerty123",
"country": "russia", "country": "russia",
"operator": "beeline", "operator": "any",
"service": "tg", "service": "vk",
"sum": 20.00 "sum": 10,
} "exceptionPhoneSet":
[
"7918",
"79281"
]
}
● Example of an answer: ● Example of an answer in case of no numbers :
{ {
"number": 79156537788, "status": "NO_NUMBERS"
"activationID": 36532, }
"status": "SUCCESS"
}
3. Delivery of SMS to the SMSBOWER server using the PUSH_SMS method
● Request fields:
Field Type Required Description
action string ü PUSH_SMS • This POST request is sent from the
partner's server to the SMSBOWER server
key string ü Protocol key
at the address:
smsId Ulong ü ID of the SMS in the partner's system [Link]
Phone number (including the country code)
phone Ulong ü
to which the SMS was sent
The sender's name (may be either • If you receive a response with the status
phoneFrom string ü alphanumeric or numeric) which sent the "SUCCESS," mark the SMS as successfully
SMS
delivered in your database and do not send
text string ü SMS text it again. If a status other than "SUCCESS"
is returned, repeat the request with a 10-
● Answer fields: second delay until you receive a
"SUCCESS" status.
Field Type Required Description
status string ü see Status Table
3. Delivery of SMS to the SMSBOWER server using the PUSH_SMS method
● Example of a request: ● Example of an answer:
{ {
"action": "PUSH_SMS", "status": "SUCCESS"
"key": " qwerty123 ", }
"smsId": 1,
"phone": 447472190082,
"phoneFrom": "Microsoft ",
"text": "Microsoft access code: 5015»
}
4. Activation completion request method FINISH_ACTIVATION
● Request fields:
Field Type Required Description
• This request is transmitted from the
action string ü FINISH_ACTIVATION SMSBOWER server to the partner's server
key string ü Protocol key to complete activation.
activationId Ulong ü Activation ID obtained in the second request • It is a POST request initiated from the
status Uint ü see Status Table SMSBOWER server to the partner's server.
● Answer fields:
Field Type Required Description
status string ü see Status Table
q 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.
4. Activation completion request method FINISH_ACTIVATION
● Example of a request: ● Example of an answer:
{ {
"action": "FINISH_ACTIVATION", "status": "SUCCESS"
"key": " qwerty123 ", }
"activationID": 100,
"status": 3
}
Testing the protocol
● 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.
TESTING PARAMETER DESCRIPTION
You should handle simultaneous requests properly and not issue numbers repeatedly. For example, if you have 100 numbers for
Simultaneous Number
Telegram United Kingdom, and SMSBOWER simultaneously makes 100 requests for Telegram United Kingdom, the partner server
Issuance
should provide 100 unique numbers. If a number is issued multiple times, the test fails.
Correct Activation
The change in activation status is fully controlled by SMSBOWER. The partner server should not autonomously complete activations.
Completion
Once you receive an SMS, you must immediately forward it to the SMSBOWER server. If you receive a status of SUCCESS, you should
SMS Delivery Verification 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
Phone number issuance should be in digital format and include the country code.
Number
Number Issuance Time
You must issue numbers with a delay of less than 3 seconds. If it takes more than 3 seconds, the testing fails.
Verification
Number Quantity
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.
Verification
Exception Handling
If you incorrectly handle exceptions for issuing a number, then testing has failed.
Verification
Status Table
● Response status: ● Successful answer to the request:
Status Description
{
SUCCESS The request was finished successfully
"status": "SUCCESS",
ERROR
Error during request execution. The ERROR //Information
field should be filled with a description
}
No numbers are available. This response is only
NO_NUMBER
returned for a number request
● Answer in case of an error:
{
● Activation status: "status": "ERROR",
"error": "Description of the error"
Status Description
}
1 Issuing a number for this service is prohibited
*The mechanism for cancellation works as
3 Activation was successfully sold. You have received a reward follows:
If a phone number has been canceled 5 times,
4 Activation was canceled*
you should not issue the same number again.
Activation has been returned. The customer has been refunded It's possible that the number was not suitable
5
for the activation. It's possible that this number was previously for the client or was already registered for the
registered, and two-factor authentication may be enabled on the specific service.
number
Data Table
LISTS LINKS
The full list of countries with names and IDs can be found at the link
List of countries
[Link]
At the moment, the breakdown by operators is under development, so you should pass the value
List of operators
“any”. Once this functionality is implemented, we will notify you through the technical support chat.
The full list of services with names and IDs can be found at the link
List of services
[Link]