SAO JSON API Beta

Basics

Mechanics of activation

Mechanics of activation process are based on the status system. Every action of user or activator causes status change. Today, these statuses are in use:

-3 - activation canceled because user requested one service, while SMS code is from another service. -2 - activation canceled by activator decision -1 - activation canceled by user decision 0 - waiting for user to send SMS 1 - waiting for SMS code from activator 2 - waiting for user to check SMS code 3 - waiting for activator to rectificate SMS code 4 - waiting for screenshot from activator 5 - waiting for user to resend SMS code 6 - activation finished by user 7 - activation finished by moderator after screenshot review 8 - activation canceled by activator because of problems with phone number (number has been abandoned) 9 - activation canceled because of error of activator (activator has been fined) 10 - activation canceled by user because of problems with phone number (number has been abandoned) 11 - waiting for moderator to review screenshot

After client receives phone number, activation is created with status 0. After that, client have 10 minutes to send SMS to this number. If a SMS was successfully sent, client should set status to 1, otherwise (for example, if number is already used in requested service), set status to 10. The activator is notified about new activation only after its status was set to 1. Activator have 10 minutes to enter received code from SMS and change activation status to 2, etc.

This communication is an activation process. You can familiarize with a full map of statuses dependencies in the chapter status dependencies.

Status dependencies

Status changes are strictly limited: only definite changes for each status are allowed and only definite person is allowed to change an activation status (user or activator). These restrictions are an activation logic.

You can familiarize with the maps of allowed status changes for each sides of activation below:

// Map of user For activation with status 0: -1 - Cancel activation 1 - Notify that SMS was send 10 - Notify about phone number problem For activation with status 1: -1 - Cancel activation For activation with status 2: 3 - Request for rectification of code from SMS* 6 - Accept code from SMS and finish activation For activation with status 3: 6 - Accept code from SMS and finish activation For activation with status 4: 6 - Accept code from SMS and finish activation For activation with status 5: -1 - Cancel activation 1 - Notify that duplicate SMS was sent

*Note that you may request for rectification of code from SMS only once. Duplicate request for resending will be marked as a screenshot request and activation status will be set to 4.

// Map of activator For activation with status 0: -2 - Cancel activation 8 - Notify about phone number problem For activation with status 1: -3 - Notify about mismatch between selected service and SMS of sender 2 - Send code from SMS 5 - Request a duplicate of SMS 8 - Notify about phone number problems For activation with status 3: 2 - Send a rectification of SMS code 9 - Admit a mistake and cancel activation For activation with status 4: 9 - Stand corrected and cancel activation 11 - Send a screenshot with SMS to moderate For activation with status 5: -2 - Cancel activation 8 - Notify about phone number problems

Statuses that were not listed in these maps are final for activation and cannot be changed.

Status dependencies map

Request format

Requests are to be sent to: http://sms-area.org/api/handler.php

Common parameters for all reqiests:


(required) "key" - API-key of your account.

(required) "method" - API-method to access.


Also, decimal separator is a decimal point.

Return values

Return values are sending in JSON format.

All methods returns JSON object of three elements:

{ //identifier of operation status "response": 0, //short description of status "description": "success", //object contains all return data "data": {} }

Non-negative values of "response" parameter means operation success. Negative values means that some error occured.

All values are grouped by meaning for convenience:

3XX - statuses for activators 2XX - statuses for users 1XX - common statuses -1XX - common server errors -2XX - wrong request parameters -3XX - temporary errors -4XX - permanent errors

Logic of error handling may be based on this grouping: for example, "common server errors" may be cause to make a repeated request after a short period of time, while after "permanent error" repeated request is useless.

Common methods

array getActivationList(string $category)

Description

This method is to get list of current activations (activations with status between 0 and 5). Parameter "category" allows you to filter activations: show only ordered by you (outcoming) or only ordered to you by someone (incoming).

Accepted parameters

(required) "category" - category of activations to get. Allowed values:

"getter" - get list of outcoming activations "setter" - get list of incoming activations (only for activators)

Return values

If request has finished successfully, method returns 0 in attribute "response" and array of activation objects in "activations" attribute, which is in attribute "data". Each object contains data about current activation:

{ "response": 0, "description": "success", "data": { //array of current activations "activations": [ { //unique ID of activation "id_activation": 615291, //unique ID of user, which requested the activation "id_getter": 1790, //unique ID of activator, who performs the activation "id_setter": 8312, //unique ID of phone number "id_number": 169290, //phone number "number": "79620710510", //symbolic ID of service, for which the activation was requested "service": "tg", //current activation status "status": 2, //array of received SMS codes "codes": ["invalid code", "valid code"], //time left to finish current step of activation, in seconds "seconds_left": 670 } ] } }

Array "codes" may contain from 0 to 2 codes. It will be empty till activator will send received SMS code to the service. If client has requested code rectification before, then array will contain two codes. Codes are arranged in the receiving order. Note that each code serves in the same format, as activator entered it. It means that you are adviced to check code for excess symbols before use.

Possible errors

-101 - SQL server error occurred, please try again -200 - API-key does not exists -211 - the category of activation list must be a string: "getter" or "setter" -400 - your account is blocked -401 - access denied

mixed getActivationStatus(int $id_activation)

Description

This method is to get detailed info about chosen activation. Activation may be current, may be got from archive as well.

Accepted parameters

(required) "id_activation" - unique ID of activation, which you want to get detailed info of.

Return values

If request was successfull, method returns 0 in attribute "response" and detailed information about activation is in attribute "data":

{ "response": 0, "description": "success", "data": { //unique ID of activation "id_activation": 171835, //unique ID of user "id_getter": 1790, //unique ID of activator "id_setter": 15271, //unique ID of phone number "id_number": 35411, //phone number "number": "79032680691", //symbolic ID of service "service": "qm", //current status of activation "status": 6, //array of received SMS codes "codes": ["357533"], //full URL points to SMS screenshot or false, if no screenshot available "screen": false, //the amount by which the balance has changed "balance_shift": -9.0, //POSIX-time of last activation status update "time": 1424267455 } }

Array "codes" may contain from 0 to 2 codes. It will be empty till activator will send received SMS code to the service. If client has requested code rectification before, then array will contain two codes. Codes are arranged in the receiving order. Note that each code serves in the same format, as activator entered it. It means that you are adviced to check code for excess symbols before use.

Possible errors

-101 - SQL server error occurred, please try again -200 - such API-key does not exist -205 - such activation does not exist in your activation-list -400 - your account is blocked

void setActivationStatus(int $id_activation, int $status, mixed $parameters)

Description

This method is to change status of activation. You can familiarize with a full map of statuses dependencies in the chapter status dependencies.

Accepted parameters

(required) "id_activation" - unique ID of activation, which status you want to change.

(required) "status" - a new status value for activation.

(optional) "parameters" - additional information to set some statuses. This parameter should be a string with code from SMS for status 2, and a file with screenshot of SMS for status 4. For other statuses this parameter should be empty.

Return values

If request was successfull, this method returns a positive number in property "response", depending on the new status value. A full list of return values:

//for activators 305 - the activation has been stoped, you are fined 304 - the screenshot of SMS-code has been submitted for moderation 303 - the resending of SMS has been requested 302 - the SMS-code has been sent 301 - the number has been marked as bad by activator 300 - the activation has been canceled by activator //for users 205 - the SMS-code has been confirmed, activation complete 204 - the screenshot of SMS-code has been requested 203 - the correction of SMS-code has been requested 202 - the readiness has been confirmed 201 - the number has been marked as bad by client 200 - the activation has been canceled by client

Field "data" will always be empty.

{ "response": 200, "description": "the activation has been canceled by client", "data": {} }

Possible errors

-101 - SQL-server error occurred, please try again -200 - such API-key does not exist -203 - such status of activation is invalid -204 - such status of activation is incorrect at current activation-step -205 - such activation does not exist in your activation-list -206 - the length of SMS-code must be less or equal than 16 characters -207 - the size of image must be less than 2Mb -208 - the MIME-type of image must be GIF, PNG, JPG, JPEG or BMP -400 - your account is blocked

float getBalance()

Description

This is a method is to get current account balance.

Accepted parameters

No parameters required.

Return values

If request was successfull, this method returns 0 in property "response" and current "balance" value in property "data":

{ "response": 0, "description": "success", "data": { //current balance "balance": 11119.4 } }

Possible errors

-100 - unexpected error occurred, please try again -101 - SQL-server error occurred, please try again -200 - such API-key does not exist -400 - your account is blocked

object getActivationSummary()

Description

This is a method is to get amount of available numbers divided by country, service and price.

Accepted parameters

No parameters required.

Return values

If request was successfull, this method returns 0 in property "response" and object "summary", contains amount of numbers, in property "data":

{ "response": 0, "description": "success", "data": { "summary": { "ru": { "vk": { //110 RU numbers for service "vk" per 9 RUR 9.0: 110, //50 numbers for service "vk" per 11.2 RUR 11.2: 50, ... }, "ok": { //894 RU numbers for service "ok" per 7.4 RUR 7.4: 894, 7.5: 35, 8.0: 1333, ... }, ... }, "ua": { "wa": { //1034 UA numbers for service "wa" per 5.5 RUR 5.5: 1034, //4207 UA numbers for service "wa" per 6.5 RUR 6.5: 4207, 7.0: 90, ... }, ... }, ... } } }

Result of this method will be cached in 5 seconds.

Possible errors

-100 - unexpected error occurred, please try again -101 - SQL-server error occurred, please try again -200 - such API-key does not exist -400 - your account is blocked

object getActivationRates()

Description

This is a method to get amount of rates, set onto account.

Accepted parameters

No parameters required.

Return values

If request was successfull, this method returns 0 in property "response" and an object "rates", contains amount of rates, in property "data":

{ "response": 0, "description": "success", "data": { //amount of rates for each service "rates": { "vk": 10.0, "mb": 5.0, "ok": 10.0, "4g": 4.0, "fb": 5.0, "ss": 5.0, "ig": 9.0, "wt": 5.0, "tg": 6.0, "vr": 9.0, "wa": 4.5, "wm": 5.1, "qm": 5.1, "ym": 5.0, "gm": 5.0, "ar": 5.1, "at": 5.0, "or": 5.0 } } }

Keys of object "rates" are symbolic ID of services. You can familiarize with a full list of symbolic IDs in the description of runActivation method.

Possible errors

-100 - unexpected error occurred, please try again -101 - SQL-server error occurred, please try again -200 - such API-key does not exist -400 - your account is blocked

mixed setActivationRates(array $rate_list)

Description

This method is to set amount of rates. Note that rate value should be positive, and its maximum value should be lower or equal to 99.9.

Accepted parameters

(required) "rate_list" - an object, with keys as symbolic ID of service and values as a rate amount. The object is similar to return value of getActivationRates method. There is an example written in PHP:

$rate_list = array ( //rate for fb (Facebook) is 5.5 RUR 'fb' => 5.5, //rate for wa (WhatsApp) is 7.0 RUR 'wa' => 7.0, //.0 is not required 'ig' => 8 //other rates do not change );

Return values

If no critical errors occured, this method returns 0 in property "response". This does not mean that sent amounts were saved. Sent values are processed and divided into four arrays, depending on processing results: "updated", "invalid", "outranged" and "unchanged". These arrays are put into "data" property:

{ "response": 0, "description": "success", "data": { //array of symbolic IDs of services which were successfully updated "updated": ["vk", "ok"], //array of symbolic IDs of services which were not updated due to invalidity or not a number value "invalid": ["invalid key of service"], //array of symbolic IDs of services which rates are beyond the allowed values "outranged": ["or", "ig", "vr"], //array of symbolic IDs of services which were not touched by request "unchanged": ["wa"] } }

So, if all sent data were successfully saved, then arrays "invalid", "outranged" and "unchanged" will be empty.

Possible errors

-100 - unexpected error occurred, please try again -101 - SQL-server error occurred, please try again -200 - such API-key does not exist -209 - the input parameter must be an array -400 - your account is blocked

array loadActivationHistory(string $category, int $limit, int $id_last, string $pattern)

Description

This method is to get archived activations (having status out of range between 0 and 5). Parameter "category" allows to filter activations: ordered by this account (outcoming) or ordered to this account (incoming).

Accepted parameters

(required) "category" - a category of activations to get. Allowed values:

"getter" - get outcoming activations "setter" - get incoming activations (for activators only)

(required) "limit" - maximum count of activations to get. Should be an integer between 1 and 1000.

(optional) "id_last" - [DESCRIPTION DELETED, PARAMETER DEPRECATED]

(optional) "pattern" - a pattern to filter activations by phone number. Allowed symbols are digits and two wildcards:

"_" - one any digit "%" - any count of any digits

Return values

If request was successfull, this method returns 0 in property "response" and array of activations named "activations" in property "data":

{ "response": 0, "description": "success", "data": { //array of archived activations "activations": [ { //unique ID of activation "id_activation": 171835, //unique ID of user "id_getter": 1790, //unique ID of activator "id_setter": 15271, //unique ID of phone number "id_number": 35411, //phone number "number": "79032680691", //symbolic ID of service "service": "qm", //current status of activation "status": 6, //array of received SMS codes "codes": ["357533"], //full URL of screenshot of SMS or false, if no screenshot has been attached "screen": false, //amount of balance change "balance_shift": -9.0, //POSIX-time of last activation status update "time": 1424267455 } ] } }

Array "codes" may contain from 0 to 2 codes. It will be empty till activator will send received SMS code to the service. If client has requested code rectification before, then array will contain two codes. Codes are arranged in the receiving order. Note that each code serves in the same format, as activator entered it. It means that you are adviced to check code for excess symbols before use.

Possible errors

-101 - SQL-server error occurred, please try again -200 - such API-key does not exist -211 - the category of activation list must be a string: "getter" or "setter" -212 - the limit of list must be unsigned integer -213 - the limit of list must be between 1 and 1000 -400 - your account is blocked -401 - access denied

User methods

mixed runActivation(string $service, string $pattern)

Description

This method is to get a phone number and create a new activation using it. Parameter "pattern" allows to choose phone number with a regular expression, which gives you a freedom: you may choose a phone number of definite country, operator and even region. Also, it allows to get an definite number, if, for example, you want to receive SMS to already used number.

Accepted parameters

(required) "service" - symbolic ID of service, which you want to activate using phone number. Available values:

"vk" - VKontakte "mb" - Mamba "ok" - Odnoklassniki "4g" - 4Game "fb" - facebook "ss" - SEOsprint "ig" - Instagram "g4" - Gem4me "tg" - Telegram "vr" - Viber "wa" - WhatsApp "wc" - WeChat "wm" - WebMoney "qm" - QIWI "ym" - Yandex "gm" - Google "ar" - auto.ru "at" - Avito "or" - Any other service

(optional) "pattern" - regular expression or predefined constant for number selection. List of predefined constants:

"ru_beeline" - Russia/Beeline "ru_mts" - Russia/MTS "ru_megafon" - Russia/Megafon "ru_tele2" - Russia/Tele2 "ru_yota" - Russia/Yota "ru" - Russia/Any "ua_beeline" - Ukraine/Beeline "ua_kyivstar" - Ukraine/Kyivstar "ua_djuice" - Ukraine/djuice "ua_mts" - Ukraine/MTS "ua_jeans" - Ukraine/Jeans "ua_life" - Ukraine/Life :) "ua" - Ukraine/Any "by" - Belarus/Any "pl" - Poland/Any "kz" - Kazakhstan/Any

Return values

If request was successfull, this method returns 206 in property "response" and an information about activation in property "data":

{ "response": 206, "description": "the activation has been started", "data": { //unique ID of new activation "id_activation": 620115, //phone number "number": "79250279950" } }

Note: Use obtained value of property "id_activation" for call methods getActivationStatus and setActivationStatus.

Possible errors

-100 - unexpected error occurred, please try again -101 - SQL-server error occurred, please try again -200 - such API-key does not exist -202 - such service of activation is invalid -300 - your balance less than your rate -301 - your rate less than rates of all online activators -305 - all relevant activators is overloaded now, please try later -307 - no numbers, please try later -400 - your account is blocked

Activator methods

mixed saveNumbers(mixed $number_list)

Description

This method is to add, change and restore phone numbers. Changing numbers means subscription or unsubscription them to activation process of selected services (for example it is allowed to unsubscribe numbers if they were used in some services). Restore of numbers means comeback of them to activation process.

Accepted parameters

(required) "number_list" - list of numbers to process. Numbers are to be sent including country code, without preceeding "+". If you want to unsubscribe number from some services, it should be sent as a key, and value of this key should be an array contains symbolic IDs of services to unsubscribe from. There is an example written in PHP:

$number_list = array ( //this number will be available to all services '79000000001', //this too '79000000002' => [], //this number will be unsubscribed from VKontakte and others '79000000003' => ['vk', 'or'], //this number is invalid and will not be processed '+7900000000' => ['at'] );

Note, that if number was already used in activation for some service at it was successfull (having status 6 or 7), then you can not subscribe it to further activations for this service.

Return values

If no errors occured, this method returns 0 in property "response". This does not mean that sent numbers were added, changed or restored. Sent values are processed and divided into six arrays, depending on processing results: "inserted", "updated", "recovered", "invalid", "taken" and "unchanged". These arrays are to be returned in property "data":

{ "response": 0, "description": "success", "data": { //array of successfully added numbers "inserted": ["79000000001", "79000000002"], //array of updated numbers "updated": ["79000000003"], //array of restored numbers "recovered": [], //array of invalid numbers "invalid": ["+7900000000"], //array of already taken numbers "taken": [], //array of unchanged numbers "unchanged": [] } }

So, if all sent numbers were added, changed or restored, arrays "invalid", "taken" and "unchanged" will be empty.

Possible errors

-101 - SQL-server error occurred, please try again -200 - such API-key does not exist -209 - the input parameter must be an array -400 - your account is blocked -401 - access denied

mixed dropNumbers(mixed $number_list)

Description

This method is to delete phone numbers. Deletion is not permanent - numbers will be marked as deleted and will not take part in activations, but will they be left in database.

Accepted parameters

(required) "number_list" - array of numbers to delete. Numbers are to be sent including country code, without preceeding "+".

Return values

If no critical errors occured, this method returns 0 in property "response". This does not mean, that sent numbers were added, changed or restored. Sent values are processed and divided into four arrays, depending on processing results: "deleted", "invalid", "unavailable" and "unchanged". These arrays are returned in property "data":

{ "response": 0, "description": "success", "data": { //array of deleted numbers "deleted": ["79000000001", "79000000002"], //array of invalid numbers "invalid": ["+7900000000"], //array of numbers, which were not assigned to account "unavailable": [], //array of unchanged numbers "unchanged": [] } }

So, if all sent phone numbers were deleted, then arrays "invalid", "unavailable" and "unchanged" will be empty.

Possible errors

-101 - SQL-server error occurred, please try again -200 - such API-key does not exist -209 - the input parameter must be an array -400 - your account is blocked -401 - access denied

array loadNumbers(string $category, int $limit, int $id_last, string $pattern)

Description

Accepted parameters

Return values

Possible errors

void setActivatorStatus(string $status)

Description

This is a method to switch between "online" and "offline" status of activator. Activator may receive activation SMS only when he is "online".

Accepted parameters

(required) "status" - new status to be set on account of activator. Allowed values:

"online" - receive orders of activation "offline" - do not receive orders of activation

If no access has been made to method getActivationList during 2 minutes, then account mode will be automitically set to "offline".

Return values

If request was successfull, this method returns 0 in property "response". Property "data" will be empty.

{ "response": 0, "description": "success", "data": {} }

Possible errors

-101 - SQL-server error occurred, please try again -200 - such API-key does not exist -210 - the status of activator must be a string: "online" or "offline" -400 - your account is blocked -401 - access denied