Activate API usage in the “Settings” of Atomic SMS Sender Control Panel (https://myatompark.com/sms/profile.php) to turn on the sms gateway. Choose “Yes” in “XML interface enabled” and choose “Real Mode” or “Test Mode” in “XML interface mode”.
If “Real Mode” is chosen the text messages will be sent immediately after incoming gateway request. If the “Test Mode” is chosen, the text messages won’t be sent at all. But tasks with “Not ready” statuses will be created. It means the connection to the gateway and the data transmission was successful.
To use API methods means to send an HTTP-request to the URL like:
http://api.atompark.com/sms/3.0/METHOD?key=public_key&sum=CONTROL_SUM&arg1=ARG_1&argN=ARG_N
where
METHOD * |
The name of the method |
KEY * |
The public key to access API |
SUM* |
The control request sum |
ARG_1 ... ARG_N |
The method arguments, separated for each method |
*All the required parameter will be marked with *
The parameters can be transmitted by GET and POST methods, all the parameters must be in UTF-8 encoding. It’s recommended to transmit all the parameters by POST method to avoid saving them in the proxy server logs.
To calculate the control sum you need:
The response comes in the JSON format object.
You can specify the public and private keys on the settings page of the server.
The example of sum calculation for addAddressbook method in PHP language.
$params ['version'] ="3.0"; $params ['action'] = "addAddressbook"; $params [‘key’] = $openKey; //you open key $params [‘name’] = “Test addressbook”; $params [‘description] = “Test description”; ksort ($params); $sum=''; foreach ($params as $k=>$v) $sum.=$v; $sum .= $privateKey; //your private key $control_sum = md5($sum);
If the method call succeed, the object will contain “result” field, its content depends on the called method, and will not contain “error” field. But even in the case of successful method running the field “warnings” may appear, it contains a package of warning objects with one- line field “warning”.
Successful method call response example:
{ "result":{ "id":18628, "name":"TEST NAME ADRESSBOOK", "phones":0, "exceptions":0, "creationdate":"2012-04-01 18:44:36", } }
The criterion of error after running a method is the existence of the “error” field with HTML error message in the response object. Besides, there will be a “code” field with the code of the error in the response object if there is any error. And the “result” field must be ignored in case of error.
{ "error":"Wrong public key.", "code":"-1", "result":"false" }
The Address Book is the object consisting of
[id] — The identifier
[name] => Name
[phones] => The quantity of telephone numbers
[exceptions] => The number of excepted telephones
[creationdate] => The date of creation
[description] => The description
The addAddressbook() method is used.
The arguments
name* |
The Address Book name |
description |
The Address Book notes |
The request example: URL:http://api.atompark.com/sms/3.0/addAddressbook?key=public_key&sum=control_sum&name=BOOK_NAME&description=BOOK_DESCRIPTION
The response:
{ "result":{ "addressbook_id":21620 } }
The unique identifier of a new Address Book addressbook_id will be returned in the response.
The delAddressbook()method is used.
The arguments
idAddressBook* |
The identifier удаляемой адресной книги |
The request example:
URL:>http://api.atompark.com/sms/3.0/delAddressbook?key=public_key&sum=control_sum&idAddressBook=21619
The response:
If the transaction is successfully completed the “result” object will contain “successful”: true.
{ "result":{ "successful":true } }
If the transaction failed:
In case you are trying to delete an Address Book that doesn’t exist the server will return
{ "error":"No addressbook", "code":"202", "result":"false" }
The editAddressbook()method is used.
The arguments
idAddressBook* |
The identifier of the Address Book to edit |
newName* |
The Address Book name |
newDescr* |
The Address Book description |
The request example:
URL:http://api.atompark.com/sms/3.0/editAddressbook?key=public_key&sum=control_sum&idAddressBook=21619&newName=name&newDescr=descr
The response:
{ "result":{ "successful":true } }
The getAddressbook( ) method is used.
The arguments
idAddressBook |
The Address Book identifier |
from |
Вернуть объекты, начиная с позиции from |
offset |
The number of objects to return |
The Address Book return is possible:
The request example:
URL:http://api.atompark.com/sms/3.0/getAddressbook?key=public_key&sum=control_sum&idAddressBook=2161
The response:
{ "result":{ "id":2161, "name":"super book", "phones":25, "exceptions":0, "creationdate":"2012-04-01 18:44:36", "description":null } }
The request example:
URL:http://api.atompark.com/sms/3.0/getAddressbook?key=public_key&sum=control_sum
The request example:
URL:http://api.atompark.com/sms/3.0/getAddressbook?key=public_key&sum=control_sum&from=3&offset=3
The response:
{ "result":{ "count":55, "fields":[ "id", "name", "phone", "date", "description" ], "data":[ [ "21597", "new book", "250", "2012-01-17 14:57:37", "" ], [ "18684", "testNAME", "0", "2012-02-06 15:08:16", "" ], [ "18661", "testNAME2", "4", "2012-03-27 22:45:47", "" ] ] } }
The Address Book search
The searchAddressBook() method is used.
The arguments
searchFields |
The “json” format object for the search. The search is possible through the next fields: “name”, “phones”, “date”. These operations can be used during the search: like,=,>,>=,<,<=. The example: { "name":{ "operation":"like", "value":"test%" } } |
from |
To return the objects starting with the “from” position |
offset |
The number of objects to return |
The request example:
URL:http://atompark.com/api/sms/3.0/searchAddressBook?key=public_key&sum=control_sum&from=10&offset=3&searchFields={ "name" : { "operation" : "like" , "value" : "test%" } }
The response:
{ "result":{ "count":50, "fields":[ "id", "name", "phone", "date", "description" ], "data":[ [ "18629", "test2", "0", "2012-01-05 16:34:15", "tstdescr" ], [ "18684", "testNAME", "0", "2012-02-06 15:08:16", "" ], [ "18661", "testNAME", "4", "2012-01-27 10:45:47", "" ] ] } }
The phone number is the object composed of:
[id]=> The phone identifier
[addressbook]=> The Address Book identifier
[phone]=> The phone number
[normalphone]=>The phone number according the international standard *
[variables]=> The variables to personalize, separated by «;» **
[status]=> The telephone number status
* international standard
** for example: Test1;Test2;Test3
The addPhoneToAddressBook()method is used.
The arguments
idAddressBook* |
The Address Book identifier |
phone* |
The phone number |
variables |
The variable to personalize |
The request example:
The request example:
URL:http://api.atompark.com/sms/3.0/addPhoneToAddressBook?key=public_key&sum=control_sum&idAddressBook=2432&phone=380638962555&variables=test
The response:
{ "result":{ "phone_id":24552302 } }
The unique phone number identifier phone_id will be returned.
The getPhoneFromAddressBook()method is used.
The arguments
idAddressBook |
The Address Book identifier |
idPhone |
The phone identifier |
phone |
The phone number |
from |
To return the objects starting with the “from” position |
offset |
The number of objects to return |
All the arguments are optional.
The request example:
URL: http://api.atompark.com/sms/3.0/getAddressbook?key=public_key&sum=control_sum&idAddressBook=2161
The response:
{ "result":{ "count":2, "fields":[ "id", "phone", "normalPhone", "variables", "status", "code" ], "data":[ [ "24552301", "380632587852", "380632587852", "test variables", "0", "" ], [ "24552302", "380632587853", "380632587853", "test variables", "0", "" ] ] } }
The request example:
URL:http://api.atompark.com/sms/3.0/getPhoneFromAddressBook?key=public_key&sum=control_sum&idPhone=24552301
The response:
{ "result":{ "id":24552301, "addressbook":18628, "phone":"380632587852", "normalphone":"380632587852", "variables":"test variables", "status":0 } }
The delPhoneFromAddressBook()method is used.
The Arguments:
idAddressBook* |
The Address Book identifier |
idPhone* |
The phone number identifier |
In order to delete all the phone numbers it is necessary to specify the Address Book identifier, but to delete a single phone you need to specify the phone number identifier.
The request example:
URL:http://api.atompark.com/sms/3.0/delPhoneFromAddressBook?key=public_key&sum=control_sum&idPhone=24552301
The response:
{ "result":{ "successful":true } }
The editPhone() method is used..
The arguments
idPhone* |
The phone identifier |
phone* |
The phone number |
variables* |
The variable to personalize |
It is necessary to input the new phone number (according to the international standard) and the new line of variables.
The request example:
URL:http://api.atompark.com/sms/3.0/editPhone?key=public_key&sum=control_sum&idPhone=24552301&phone=380657412569&variables=test
The response:
{ "result":{ "successful":true } }
The searchPhones() method is used..
The arguments
searchFields |
The “json” format object for the search. The search is possible through the following fields: “idAddressBook”, “phones”, “normalPhone”, “variables”, “status”. These operations can be used during the search: like,=,>,>=,<,<=. The example: { "phone":{ "operation":"like", "value":"38063%" } } |
from |
To return the objects starting with the “from” position |
offset |
The number of objects to return |
The request example:
URL:{ "variables" : { "operation" : "like" , "value" : "иван%" } }">http://api.atompark.com/sms/3.0/searchPhones?key=public_key&sum=control_sum&searchFields={ "variables" : { "operation" : "like" , "value" : "иван%" } }
The response:
{ "result":{ "count":1, "fields":[ "id", "idAddressBook", "phone", "normalPhone", "variables", "status", "code", "maid" ], "data":[ [ "24552295", "21597", "9999999999", "9999999999", "Иван Васильевич", "0", "", "0" ] ] } }
The exception is the object composed of:
[id] => The identifier
[phone] =>The phone number
[added] => The adding date
[comment] => The description
The addPhoneToExceptions() method is used.
The arguments
idPhone |
The phone identifier |
phone |
The phone number |
reason |
The reason of adding to the exceptions |
To add the phone to the exceptions it is necessary to relay the phone identifier or the phone number.
The request example:
URL: http://api.atompark.com/sms/3.0/addPhoneToExceptions?key=public_key&sum=control_sum&idPhone=24552291&reason=test_add
The response:
{ "result":{ "exseption_id":24552302 } }
The unique exception identifier exception_id will be returned in the response.
The delPhoneFromExceptions() method is used.
The arguments
idPhone |
The phone identifier |
phone |
The phone number |
idException |
The exception identifier |
To delete the telephone number it is necessary to relay one of these parameters.
The request example:
URL:>http://api.atompark.com/sms/3.0/delPhoneFromExceptions?key=public_key&sum=control_sum&idPhone=24552291
The response:
{ "result":{ "successful":true } }
The editExceptions() method is used.
The arguments
idException* |
The exception identifier |
reason* |
The detailed reason of adding the phone to the exceptions |
The request example:
URL:
http://api.atompark.com/sms/3.0/delPhoneFromExceptions?key=public_key&sum=control_sum&idPhone=24552291
The response:
{ "result":{ "successful":true } }
The getException() method is used.
The arguments
idException |
The exception identifier |
phone |
The phone number |
idAddresbook |
The Address Book identifier |
from |
To return the objects starting with the “from” position |
offset |
The number of objects to return |
The request example:
URL:
http://api.atompark.com/sms/3.0/delPhoneFromExceptions?key=public_key&sum=control_sum&idPhone=24552291
The response:
{ "result":{ "id":181042, "phone":"380692587852", "added":"2012-04-04 10:55:08", "comment":"testREASON_PHONE" } }
The request example:
URL:http://api.atompark.com/sms/3.0/getException?key=public_key&sum=control_sum&from=1&offset=2
The response:
{ "result":{ "count":6, "fields":[ "id", "phone", "added", "comment" ], "data":[ [ "181038", "99999999999", "2012-03-12 10:44:31", "testREAS!!!" ], [ "181042", "88888888888", "2012-04-04 10:55:08", "testREASON_PHONE" ] ] } }
The searchPhonesInExceptions() method is used..
The arguments
searchFields |
The “json” format object for the search. The search is possible through the next fields: “id”, “phone”, “date”, “descr”. These operations can be used during the search: like,=,>,>=,<,<=. The example { "descr":{ "operation":"like", "value":"testR%" } } |
from |
To return the objects starting with the “from” position |
offset |
The number of objects to return |
The request example:
URL:{ "variables" : { "operation" : "like" , "value" : "иван%" } }"> http://api.atompark.com/sms/3.0/searchPhones?key=public_key&sum=control_sum&searchFields={ "variables" : { "operation" : "like" , "value" : "иван%" } }
The response:
{ "result":{ "count":6, "fields":[ "id", "phone", "added", "comment" ], "data":[ [ "181041", "91234561", "2012-04-04 10:11:40", "testREASON_PHONE" ], [ "181038", "74999404711", "2012-03-12 10:44:31", "testREASasdON!!!" ] ] } }
“currency” |
the currency |
“balance_currency” |
– the balance in the chosen currency |
The request example:
URL:http://api.atompark.com/sms/3.0/getUserBalance?key=public_key&sum=control_sum¤cy=USD
The response:
{ "result":{ "currency":"USD", "balance_currency":2.5 } }
The registerSender() method is used.
The arguments
name |
The sender name. No more than 14 numerals for numeric sender ID, and no more than 11 symbols for textual sender ID. |
country |
The country to register the name in. Currently the following countries require sender ID registration: MD,UA. |
The request example:
URL:
http://api.atompark.com/sms/3.0/registerSender?key=public_key&sum=control_sum&name=qwerty&country=UA
The response:
{ "name_id":748, "status":0 }
The status in the “status” field will be returned in the response:
0 – pending approval
1 — approved
2 — denied
The getSenderStatus() method is used.
The arguments
idName |
The sender name identifier |
name |
The sender name |
country |
The country |
from |
To return the objects starting with the “from” position |
offset |
The number of objects to return |
To get the sender status it is necessary to transmit the sender name identifier or to transmit the sender name and the country. To get all the objects specify the offset.
The request example:
URL:http://api.atompark.com/sms/3.0/getSenderStatus?key=public_key&sum=control_sum&idName=747
или
URL: http://api.atompark.com/sms/3.0/getSenderStatus?key=public_key&sum=control_sum&name=qwerty&country=ua
The response:
{ "result":{ "id":747, "name":"qwerty", "status":"0", "country":"UA" } }
URL: http://api.atompark.com/sms/3.0/getSenderStatus?key=public_key&sum=control_sum&from=10&offset=2
The response:
{ "result":{ "count":661, "fields":[ "id", "country", "name", "status", "description" ], "data":[ [ "11", "UA", "test", "1", "" ], [ "12", "UA", "test1", "1", "" ] ] } }
The createCampaign() method is used.
The arguments:
sender |
The sender identifier |
text |
The text message content |
list_id |
The Address Book identifier |
datetime |
To send by parts – the number of sms per transaction |
batch |
To send by parts – the interval between the deliveries, minutes |
batchinterval |
To send by parts – the interval between the deliveries, minutes |
sms_lifetime |
Sms lifetime (0=maximum) |
control_phone |
The control phone number |
The “datetime” parameter is used if the campaign must be sent not immediately, but be scheduled. For the immediately delivery this parameter needs to be empty.
The example of date format during the parameter transmission – 2012-05-01 00:20:00
The “batch” and “batchinterval” parameters are used if the delivery needs to be sent by parts. If the delivery is planned by an iteration, the parameters must be transmitted with the 0 value.
The optional parameter “control_phone” is specified if the delivery quality control on the input phone is necessary. The phone number must be in the international standard format.
The request example:
URL: http://api.atompark.com/sms/3.0/createCampaign?key=public_key&sum=control_sum&sender=Info&text=Testing%20SMS&list_id=1234&datetime=&batch=0&batchinterval=0&sms_lifetime=0&controlnumber=
The response:
{ "result":{ "id":1853173, "price":403.44 } }
Where id is the created campaign identifier, price is the value of the delivery in the currency, specified in the user settings.
The sendSMS() method is used.
The arguments:
sender |
The sender identifier |
text |
the text message content |
phone |
The recipient phone number |
datetime |
To schedule the campaignя |
sms_lifetime |
The sms lifetime (0=maximum, 1, 6, 12, 24 hours) |
The “datetime” parameter is used if it is necessary not to send the delivery immediately but to schedule it. For the immediately delivery just transmit the empty parameter. The example of date format during the parameter transmission – 2012-05-01 00:20:00
The request example:
URL:
http://api.atompark.com/sms/3.0/sendSMS?key=public_key&sum=control_sum&sender=Info&text=Testing%20SMS&phone=380972920383&datetime=&sms_lifetime=0
The response:
{ "result":{ "id":1853174, "price":0.13 } }
Where id is the created campaign identifier, price is the value of the delivery in the currency, specified in the user settings.
The getCampaignInfo() method is used.
The arguments:
id |
The campaign identifier that was created by sendSMS() or createCampaign(). |
The request example:
URL: http://api.atompark.com/sms/3.0/getCampaignInfo?key=public_key&sum=control_sum&id=128891
The response:
{ "result":{ "sent":1, "delivered":1, "not_delivered":0, "price":0.13, "status":3 } }
where:
sent – the number of sent text messages
delivered – the number of delivered text messages
not_delivered – the number of undelivered text messages
price – the price of all the campaign
status – the campaign state
The variable “status” can have such values:
0 |
The message is in the waiting line |
1 |
There is no enough money to start the delivery |
2 |
The delivery is in the progress |
3 |
Sent |
4 |
There are no valid recipient numbers |
5 |
Partially sent |
6 |
Spam |
7 |
The recipient name is invalid |
8 |
Pause |
9 |
The delivery is scheduled |
10 |
The campaign is pending manual approval |
The getCampaignDeliveryStats() method is used.
The arguments:
id |
The campaign identifier that was created by sendSMS() or createCampaign(). |
datefrom |
This parameter is not required. If it’s specified the statuses will be got after last “date from” upgrading. |
The request example:
URL: http://api.atompark.com/sms/3.0/getCampaignDeliveryStats?key=public_key&sum=control_sum&id=128891
The response:
{ "result":{ "phone":[ "380972920383" ], "sentdate":[ "0000-00-00 00:00:00" ], "donedate":[ "0000-00-00 00:00:00" ], "status":[ "0" ] } }
where:
phone – the telephone package
sentdate –the time sending package
donedate – the last status setting package
status – the text message state package
The variables in “status” can be of such values:
0 |
In the waiting line |
SENT |
Sent |
DELIVERED |
Delivered |
NOT_DELIVERED |
Undelivered |
INVALID_PHONE_NUMBER |
Invalid recipient number |
SPAM |
Spam |
If the field “sentdate” contains the value “0000-00-00 00:00:00” it means that a text message is still in the waiting line. As well, if “donedate” contains “0000-00-00 00:00:00” it means that the final status hasn’t been got from the operator.
The cancelCampaign() method is used.
The arguments:
id |
The identifier кампании, созданной при помощи sendSMS() или createCampaign () |
Отменить рассылку можно в том случае, если еще не началась ее отправка.
The request example:
URL:http://api.atompark.com/sms/3.0/cancelCampaign?key=public_key&sum=control_sum&id=128891
The response:
{ "result":{ "successful":1 } }
The deleteCampaign() method is used.
The arguments:
id |
The campaign identifier that was created by sendSMS() or createCampaign(). |
The request example:
URL: http://api.atompark.com/sms/3.0/deleteCampaign?key=public_key&sum=control_sum&id=128891
The response:
{ "result":{ "successful":1 } }
If the delivery has been already deleted, the response will contain an error message. The delivery can be deleted in spite of the current status.
The checkCampaignPrice() method is used.
The arguments:
sender |
The sender identifier |
text |
the text message content |
list_id |
The Address Book identifier |
The request example:
URL: http://api.atompark.com/sms/3.0/checkCampaignPrice?key=public_key&sum=control_sum&sender=Info&text=Testing%20SMS&list_id=1234
The response:
{ "result":{ "price":1210.32 } }
The getCampaignList() method is used
There are no Arguments.
The request example:
URL: http://api.atompark.com/sms/3.0/getCampaignList?key=public_key&sum=control_sum
The response:
{ "result":{ "id": [ "10012", "10013" ], "from": [ "Sender1", "Sender2" ], "body": [ "Text of SMS1", "Text of SMS2" ], "status" : [ 3, 3 ] } }
The field “status” has the same value as in the table for getCampaignInfo() option.
Developers who need additional free SMS for testing please email us at 911@atompark.com
Top up account and start sending SMS from your Member Area right now
Top up account