Atomic SMS Sender API (v.3.0)

To activate API 3.0. usage, please login Atomic SMS Sender accout and in the Settings section -> Atomic SMS Sender tab choose “Yes” in the Active API 3.0.

Note! Unlike the XML interface in API 3.0 the test mode is activated by transferring the test=1 parameter. Please note that the current parameter is also used in the checksum generating, if exists.

API Usage Basics

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

*All the required parameter are marked with *

The parameters can be transmitted by GET and POST methods, and all the parameters must be in UTF-8 encoding. It is recommended that you transmit all the parameters using the POST method to avoid saving them in the proxy server logs.
To calculate the control sum, you must:

1. Sort all the incoming keys
2. Make a concatenation value over those keys
3. Make a concatenation over received value with a private key
4. Take an MD5 from the received result

The response will be in a JSON format object.

You can specify the public and private keys on the service settings page.

Below is an example of sum calculation for the addAddressbook method using the 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);

Successful method call results

If the method call succeed, the object will contain “result” field, the content of which depends on the called method, and will not contain “error” field. But even when the method run successfully, the “warnings” field may appear, containing a package of warning objects with one-line “warning” field.

Successful method call response example:

{
   "result":{
      "id":18628,
      "name":"TEST NAME ADRESSBOOK",
      "phones":0,
      "exceptions":0,
      "creationdate":"2012-04-01 18:44:36",
   }
} 

Error response example

The error criterion after the method running is the existence of an “error” field. It contains an HTML error message in the response object. Additionally, there will be a “code” field with an error code in the response object. The "result" field will be ignored in case of error.

{
   "error":"Wrong public key.",
   "code":"-1",
   "result":"false"
} 
 

Methods

Address Book Operations

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

To create the Address Book

Method addAddressbook() is used.

Arguments

Request example: URL: http://api.atompark.com/sms/3.0/addAddressbook?key=public_key&sum=control_sum&name=BOOK_NAME&description=BOOK_DESCRIPTION

Response:

{
   "result":{
      "addressbook_id":21620
   }
} 
 

The unique identifier of a new Address Book addressbook_id will be returned in the response.

To delete the Address Book

Method delAddressbook() is used.

Arguments

Request example:
URL: http://api.atompark.com/sms/3.0/delAddressbook?key=public_key&sum=control_sum&idAddressBook=21619

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"
} 

  

To edit the Address Book

Method editAddressbook() is used.
Arguments

Request example:
URL: http://api.atompark.com/sms/3.0/editAddressbook?key=public_key&sum=control_sum&idAddressBook=21619&newName=name&newDescr=descr

Response:

{
   "result":{
      "successful":true
   }
} 
  

To get the Address Book

Method getAddressbook( ) is used.

Arguments

The Address Book return is possible:

• With the specified identifier

Request example:
URL:http://api.atompark.com/sms/3.0/getAddressbook?key=public_key&sum=control_sum&idAddressBook=2161

Response:

{
   "result":{
      "id":2161,
      "name":"super book",
      "phones":25,
      "exceptions":0,
      "creationdate":"2012-04-01 18:44:36",
      "description":null
   }
} 

• without specified identifier all the Address Books will be returned.

Request example:
URL:http://api.atompark.com/sms/3.0/getAddressbook?key=public_key&sum=control_sum

• without specified identifier, but with specified offset, all the Address Book that corresponds to the offset will be returned

Request example:
URL:http://api.atompark.com/sms/3.0/getAddressbook?key=public_key&sum=control_sum&from=3&offset=3

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
Method searchAddressBook() is used.

Arguments

		{
		   "name":{
			  "operation":"like",
			  "value":"test%"
		   }
		}	  

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%" } }

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",
            ""
         ]
      ]
   }
} 
  

Address book cloning

Method getAddressbook( ) is used.
This method is used to make a copy of an existing address book with a new ID.
Arguments:

Request example:
URL: http://api.atompark.com/sms/3.0/cloneaddressbook?key=public_key&sum=control_sum&idAddressBook=147

Response:

{
   "result":{
      "successful":true,
	  "idAddressBook":36107
   }
} 

The phone numbers operations

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

Adding the phone number to the Address Book

Method addPhoneToAddressBook() is used.
Arguments

Request example:
URL:http://api.atompark.com/sms/3.0/addPhoneToAddressBook?key=public_key&sum=control_sum&idAddressBook=2432&phone=380638962555&variables=test

Response:

{
   "result":{
      "phone_id":24552302
   }
} 
 

The unique phone number identifier phone_id will be returned.

Add phone numbers to Address Book

Method addPhoneToAddressBook() is used.
Arguments:

Request example:
URL: http://api.atompark.com/sms/3.0/addPhoneToAddressBook?key=public_key&sum=control_sum&idAddressBook=2432&data=[["38063169xxx1","test1"],["38063169xxx2","test2"],["38063169xxx3","test3"],["38063169xxx3","test4"],["38063169xxx4"],["38063169xxx5","test5"]]

Response:

{
   "result":{
      "successful":true
   }
} 
 

Getting the Address Book

Method getPhoneFromAddressBook() is used.

Arguments

All the arguments are optional.

Request example:
URL: http://api.atompark.com/sms/3.0/getAddressbook?key=public_key&sum=control_sum&idAddressBook=2161

Response:

{
   "result":{
      "count":2,
      "fields":[
         "id",
         "phone",
         "normalPhone",
         "variables",
         "status",
         "code"
      ],
      "data":[
         [
            "24552301",
            "380632587852",
            "380632587852",
            "test variables",
            "0",
            ""
         ],
         [
            "24552302",
            "380632587853",
            "380632587853",
            "test variables",
            "0",
            ""
         ]
      ]
   }
}

  

Request example:
URL:http://api.atompark.com/sms/3.0/getPhoneFromAddressBook?key=public_key&sum=control_sum&idPhone=24552301

Response:

{
   "result":{
      "id":24552301,
      "addressbook":18628,
      "phone":"380632587852",
      "normalphone":"380632587852",
      "variables":"test variables",
      "status":0
   }
} 
  

Deleting phone numbers from the Address Book.

Method delPhoneFromAddressBook() is used.

Arguments:

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.

Request example:
URL: http://api.atompark.com/sms/3.0/delPhoneFromAddressBook?key=public_key&sum=control_sum&idPhone=24552301

Response:

{
   "result":{
      "successful":true
   }
} 
  

Delete a group of phone numbers from the address book

Method delphonefromaddressbookgroup() is used.
Arguments:

Request example:
URL: http://api.atompark.com/sms/3.0/delphonefromaddressbookgroup?key=public_key&sum=control_sum&idPhones=456,523,985,412

Response:

{
   "result":{
      "successful":true
   }
} 
 

Editing phone numbers in the Address Book

Method editPhone() is used.
Arguments

It is necessary to input the new phone number (according to the international standard) and the new line of variables.

Request example:
URL: http://api.atompark.com/sms/3.0/editPhone?key=public_key&sum=control_sum&idPhone=24552301&phone=380657412569&variables=test

Response:

{
   "result":{
      "successful":true
   }
} 
 

Looking up phone numbers in the Address Book

Method searchPhones() is used.
Arguments

{
   "phone":{
      "operation":"like",
      "value":"38063%"
   }
}	  

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" : "иван%" } }

Response:

{
   "result":{
      "count":1,
      "fields":[
         "id",
         "idAddressBook",
         "phone",
         "normalPhone",
         "variables",
         "status",
         "code",
         "maid"
      ],
      "data":[
         [
            "24552295",
            "21597",
            "9999999999",
            "9999999999",
            "Иван Васильевич",
            "0",
            "",
            "0"
         ]
      ]
   }
} 
  
  

The exceptions operations.

The exception is the object composed of:
[id] => The identifier
[phone] =>The phone number
[added] => The adding date
[comment] => The description

To add the telephone number to the exceptions

Method addPhoneToExceptions() is used.
Arguments

To add the phone to the exceptions it is necessary to relay the phone identifier or the phone number.
Request example:
URL: http://api.atompark.com/sms/3.0/addPhoneToExceptions?key=public_key&sum=control_sum&idPhone=24552291&reason=test_add

Response:

{
   "result":{
      "exseption_id":24552302
   }
} 
 

The unique exception identifier exception_id will be returned in the response.

Deleting phone numbers from the exceptions

Method delPhoneFromExceptions() is used.
Arguments

To delete the telephone number it is necessary to relay one of these parameters.

Request example:
URL:http://api.atompark.com/sms/3.0/delPhoneFromExceptions?key=public_key&sum=control_sum&idPhone=24552291

Response:

{
   "result":{
      "successful":true
   }
} 

 

Editing phone numbers in the exceptions

Method editExceptions() is used.
Arguments

Request example:
URL: http://api.atompark.com/sms/3.0/delPhoneFromExceptions?key=public_key&sum=control_sum&idPhone=24552291

Response:

{
   "result":{

      "successful":true
   }
} 
  

Getting the exception object

Method getException() is used.
Arguments

Request example:
URL: http://api.atompark.com/sms/3.0/delPhoneFromExceptions?key=public_key&sum=control_sum&idPhone=24552291

Response:

{
   "result":{
      "id":181042,
      "phone":"380692587852",
      "added":"2012-04-04 10:55:08",
      "comment":"testREASON_PHONE"
   }
} 
  
  

Request example:
URL:http://api.atompark.com/sms/3.0/getException?key=public_key&sum=control_sum&from=1&offset=2

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"
         ]
      ]
   }
} 
  

Searching through exceptions

Method searchPhonesInExceptions() is used.
Arguments

{
   "descr":{
      "operation":"like",
      "value":"testR%"
   }
} 
	  

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" : "иван%" } }

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!!!"
         ]
      ]
   }
} 
  
  

Checking the balance

Method getUserBalance() method is used.
Arguments

Request example:
URL:http://api.atompark.com/sms/3.0/getUserBalance?key=public_key&sum=control_sum¤cy=USD

Response:

{
   "result":{
      "currency":"USD",
      "balance_currency":2.5
   }
} 

  

The sender name registration

Method registerSender() is used.
Arguments

Rquest example:
URL: http://api.atompark.com/sms/3.0/registerSender?key=public_key&sum=control_sum&name=qwerty&country=UA

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

Getting the sender status

Method getSenderStatus() is used.
Arguments

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.

Request example:
URL:http://api.atompark.com/sms/3.0/getSenderStatus?key=public_key&sum=control_sum&idName=747

or

URL: http://api.atompark.com/sms/3.0/getSenderStatus?key=public_key&sum=control_sum&name=qwerty&country=ua

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

Response:

{
   "result":{
      "count":661,
      "fields":[
         "id",
         "country",
         "name",
         "status",
         "description"
      ],
      "data":[
         [
            "11",
            "UA",
            "test",
            "1",
            ""
         ],
         [
            "12",
            "UA",
            "test1",
            "1",
            ""
         ]
      ]
   }
}   
  

Bulk sms operations

Creating a campaign

Method createCampaign() is used.
Arguments:

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 additional parameter “userapp” can be used to identify the campaign source. If you want to know how many sms messages were sent via your application/module/service — specify its name into this parameter, the statistics will be available on request.
Attention! This parameter is not involved in the formation of a checksum.
It is better to transfer this parameter for creating campaign methods as following:
createcampaign
sendsms
sendsmsgroup

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=

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.

Sending a single the text message to a particular phone number

Method sendSMS() is used.
Arguments:

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

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

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.

Send SMS to a group

Method sendsmsgroup() is used.
Arguments:

Request example:
URL: http://api.atompark.com/sms/3.0/sendsmsgroup?key=public_key&sum=control_sum&sender=senderid&text=text&datetime=2013-01-19 00:00:00&sms_lifetime=0&phones=[["3806316923xx","Sergey"],["3806316923xx","test"],["3806785214xx"],["3806785214xx"]]

Response:

{
   "result":{
      "id":9097982,
	  "price":0.5592,
	  "currency":"UAH"
   }
} 
 

Getting information over the campaign results

Method getCampaignInfo() is used.
Arguments:

Request example:
URL: http://api.atompark.com/sms/3.0/getCampaignInfo?key=public_key&sum=control_sum&id=128891

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:

Getting the sms delivery statuses

Method getCampaignDeliveryStats() is used.
Arguments:

Request example:
URL:http://api.atompark.com/sms/3.0/getCampaignDeliveryStats?key=public_key&sum=control_sum&id=128891

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:

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.

Cancelling the delivery

Method cancelCampaign() is used.
Arguments:

To cancel the delivery is possible only before it’s starting.
Request example:
URL: http://api.atompark.com/sms/3.0/cancelCampaign?key=public_key&sum=control_sum&id=128891

Response:

{
"result":{
"successful":1
}
}

Deleting the delivery

Method deleteCampaign() is used.
Arguments:

Request example:
URL: http://api.atompark.com/sms/3.0/deleteCampaign?key=public_key&sum=control_sum&id=128891

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.

Checking the campaign price according to the specified text message and the list

Method checkCampaignPrice() is used.
Arguments:

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

Response:

{
"result":{
"price":1210.32
}
}

    

Get campaigns price

Method checkCampaignPriceGroup() is used.
Arguments:

Request example:
URL: http://api.atompark.com/sms/3.0/checkCampaignPriceGroup?key=public_key&sum=control_sum&sender=senderid&text=text&phones=[["3806316923xx","Sergey"],["3806316923xx","test"],["3806785214xx"],["3806785214xx"]]

Response:

{
   "result":{
      "price":0.5592,
	  "currency":"UAH"
   }
} 
 

Getting the list of campaigns

Method getCampaignList() is used
There are no Arguments.
Request example:
URL: http://api.atompark.com/sms/3.0/getCampaignList?key=public_key&sum=control_sum

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.

Get messages statuses due to campaigns

Method getcampaigndeliverystatsgroup() is used.
Arguments:

Request example:
URL: http://api.atompark.com/sms/3.0/getcampaigndeliverystatsgroup?key=public_key&sum=control_sum&id=754,751

Response:

{
   "result":{
      "phone":["3806316923xx","3806316923xx"],
	  "sentdate":["0000-00-00 00:00:00","0000-00-00 00:00:00"],
	  "donedate":["0000-00-00 00:00:00","0000-00-00 00:00:00"],
	  "status":["0","0"],"id":[97659179,97659180]
   }
} 
 

Get task status

Method gettaskinfo() is used.
Arguments:

Request example:
URL: http://api.atompark.com/sms/3.0/gettaskinfo?key=public_key&sum=control_sum&taskIds=97659003,97659005

Response:

{
   "result":[
   {
      "id":97659003,
	  "phone":"79503702408",
	  "country":0,
	  "parts":"1",
	  "sentdate":"2012-12-07 10:14:29"
	  "donedate":"0000-00-00 00:00:00",
	  "price":0.123,
	  "status":"0",
	  "variable":"",
	  "currency":"UAH"
   }
   {
	  "id":97659005,
      "phone":"79503703937"
	  "country":0,
	  "parts":"1"
	  "sentdate":"2012-12-07 10:14:29"
	  "donedate":"0000-00-00 00:00:00"
	  "price":0.123,
	  "status":"0",
	  "variable":"",
	  "currency":"UAH"
	}
	]
} 
 

Developers who need additional free SMS for testing please email us at 911@atompark.com