Bulk SMS Service API - API Documentation

Adding telephone numbers to a mailing list

To add telephone numbers to a list of recipients, submit a POST request to

https://api.sendpulse.com/sms/numbers

Request parameters:

addressBookId	ID of the mailing list (int)
phones	bulk telephone list in json format

A sample response to retrieving mailing list information request:

[
 {
   "result": true,
   "counters": {
     "added": 0,
     "exceptions": 0,
     "exists": 83
   }
 }
]

Updating a list of variables by a phone number

To update a list of variables by a phone number, submit a PUT request to

https://api.sendpulse.com/sms/numbers

Request parameters:

addressBookId	ID of the mailing list (int)
phones	bulk telephone list in json format
variables	array of variables in json format

Sample Phones parameter:


["380933170413","380988365096","380956045455","380635962561"]

Sample Variables parameter:


[{"name":"test1","type":"date", "value":"2018-10-10"},
 {"name":"test2","type":"string", "value":"czxczxczx"},
 {"name":"test3", "type":"number", "value":12312312312}]

Sample response:

[
 {
   "result": true,
   "counters": {
     "updated": 4
   }
 }
]

Deleting telephone numbers from a mailing list

To delete a phone number from a mailing list, submit a DELETE request to

https://api.sendpulse.com/sms/numbers

Request parameters:

phones	bulk telephone list in json format
addressBookId	mailing list ID

A sample response:

[
 {
   "result": true,
   "counters": {
     "added": 0,
     "exists": 3

   }
 }
]

Retrieving information for a specific phone number

To retrieve information for a specific phone number, submit a GET request to

https://api.sendpulse.com/sms/numbers/info/{addressBookId}/{phoneNumber}

Request parameters:

phoneNumber	a phone number
addressBookId	a mailing list ID

A sample response:

[
 {
   "result": true,
   "data": {
     "status": 1,
     "variables": {
       "test1": "2018-10-10",
       "test2": "czxczxczx",
       "test3": 12312312312
     },
    "added": "2017-02-21 13:19:47" 
    }
 }
]

Adding telephone number to the blacklist

To add a telephone number to the blacklist submit a POST request to

https://api.sendpulse.com/sms/black_list

Request parameters:

phones	bulk telephone list in json format
description	description

A sample response:

[
 {
   "result": true,
   "counters": {
     "added": 2,
     "exists": 3 
    }
 }
]

Deleting a phone number from the blacklist

To delete a phone number from the blacklist, submit a DELETE request to

https://api.sendpulse.com/sms/black_list

Request parameters:

phones

the bulk telephone list in json format

A sample response:

[
 {
	"result": true,
	"counters": {
		"removed": 3
    }
 }
]

Viewing the blacklist

To view the blacklist, submit a GET request to

https://api.sendpulse.com/sms/black_list

A sample response:


[
 {
   "result": true,
   "data": [ {
		"phone": 380506383302,
		"description": "texst",
		"add_date": "2017-02-27 10:48:22"
	},
	]
  }
]

Retrieving information on telephone numbers in the blacklist

To retrieve information of telephone numbers in the blacklist submit a GET request to

https://api.sendpulse.com/sms/black_list/by_numbers

Request parameters:

phones

a list of telephone numbers in json format

A sample response:


[
  {
   "result": true,
   "data": [ {
		"phone": 380506383302,
		"description": "texst",
		"add_date": "2017-02-27 10:48:22"
	},
	]
}
]

Creating a campaign

To create a campaign submit a POST request to

https://api.sendpulse.com/sms/campaigns

Request parameters:

sender	alphanumeric value, 11 symbols max
addressBookId	mailing list
body	text of the campaign
transliterate	1 or 0, transliteration of the body
route*	list of routes for various countries in JSON (optional), example `{"UA":"national", "BY":"international"}`
date	date of the campaign in Y-m-d H:i:s format (optional)
emulate	this optional parameter activates Test mode: if emulate=1, campaign will be formed, but not sent, and it will not be displayed in user panel; in API reply, the campaign id will =0.

Note, that some operators require specification of the message delivery route: national or international. Operators of some countries also require a registered sender ID. If you don't have a registered sender ID for such countries, the international route must be used.

*All messages undergo moderation, so it may take up to several minutes to deliver your SMS to the recipient.

A sample response:


[
 {
  "result": true,
  "campaign_id": 2623084
 }
]

Creating a campaign by a list of phone numbers

To create a campaign by a list of phone numbers, submit a POST request to

https://api.sendpulse.com/sms/send

Request parameters:

sender	sender alphanumeric value, 11 symbols max
phones	bulk telephone list in json format
body	text of the message
transliterate	1 or 0, transliteration of the message body
date	date of the campaign in Y-m-d H:i:s format (optional)
route	list of routes for various countries in JSON (optional)
emulate	this optional parameter activates Test mode: if emulate=1, campaign will be formed, but not sent, and it will not be displayed in user panel; in API reply, the campaign id will =0.

*All messages undergo moderation, so it may take up to several minutes to deliver your SMS to the recipient.

A sample response:


[
 {
   "result": true,
   "campaign_id": 2623085,
   "counters": {
     "exceptions": 0,
     "sends": 3
   }
 }
]

Retrieving a list of campaigns by date

To retrieve a list of campaigns by date, submit a GET request to

https://api.sendpulse.com/sms/campaigns/list

Request parameters:

dateFrom	the date from in Y-m-d H:i:s format
dateTo	the date until in Y-m-d H:i:s format

Sample response:


[
 {
   "result": true,
   "data": [ {
     "id": 2136035,
     "address_book_id": 0,
     "company_price": 0.81,
     "company_currency": "USD",
     "send_date": "2017-01-18 08:15:18",
     "date_created": "2017-01-18 08:15:18",
     "sender_mail_address": "",
     "sender_mail_name": "",
     "external_stat": []
   }, 
   {
   "id": 2136036,
   "address_book_id": 0,
   "company_price": 0.27,
   "company_currency": "USD",
   "send_date": "2017-01-18 11:59:52",
   "date_created": "2017-01-18 11:59:52",
   "sender_mail_address": "",
   "sender_mail_name": "",
   "external_stat": []
   },
   ]
 }
]

Retrieving a campaign information

To retrieve a campaign information submit a GET request to

https://api.sendpulse.com/sms/campaigns/info/{id}

Request parameters:

{id}	the ID of the campaign

A sample response:


[  
   {  
      "result":true,
      "data":{  
         "id":7520226,
         "address_book_id":12458,
         "currency":"USD",
         "company_price":0.044,
         "send_date":"2018-09-13 11:03:22",
         "date_created":"2018-09-13 11:03:22",
         "sender_name":"111111",
         "task_phones_info":[  
            {  
               "phone":18085426859,
               "status":2,
               "status_explain":"Delivered",
               "сountry_code":"USA",
               "money_spent":0.022
            },
            {  
               "phone":18037080295,
               "status":2,
               "status_explain":"Delivered",
               "сountry_code":"USA",
               "money_spent":0.022
            }
         ]
      }
   }
]

Description of status sending to the phone:

status code	status	status description
0	ready to send	message is ready to be sent
1	sent	message sent
2	delivered	message delivered
12	not delivered	message was not delivered

Canceling a campaign in a case when the sending has not started

To cancel a campaign submit a PUT request to

https://api.sendpulse.com/sms/campaigns/cancel/{id}

Request parameters:

{id}	the ID of the mailing

A sample response:


[
 {
   "result": false
 }
]

Calculating the cost of a campaign

To calculate the cost of a campaign submit a GET request to

https://api.sendpulse.com/sms/campaigns/cost

Request parameters:

addressBookId	mailing list
phones	bulk telephone list in json format (optional)
body	Body of the message
sender	sender
route	list of routes for various countries in JSON optional), example `{"UA":"national", "BY":"international"}`

Please note that parameters need to be encoded to URL format

If mailing list is not specified, the list of phone numbers should be specified and vice versa.

A sample response:


[
 {
   "result": true,
   "data": {
     "price": 0.05,
     "currency": "USD" 
   }
 }
]

Retrieving list of sender ID

To retrieve information about sender ID's in account submit a GET request to

https://api.sendpulse.com/sms/senders

A sample response:

[
      {
        "id": 4786,
        "sender": "iQA",
        "country": "Turkey",
        "country_code": "TR",
        "status": 1,
        "status_explain": "Active"
    },
    {
        "id": 4787,
        "sender": "iQA",
        "country": "Turkey",
        "country_code": "TR",
        "status": 1,
        "status_explain": "Active"
    },
    {
        "id": 18027,
        "sender": "rejectit",
        "country": "Turkey",
        "country_code": "TR",
        "status": 0,
        "status_explain": "On moderation"
    }
]

Description of status codes:

0	on moderation
1	active
2	rejected

Deleting a campaign

To delete a campaign submit a DELETE request to

https://api.sendpulse.com/sms/campaigns

Request parameters:

id	a campaign ID

A sample response:

[
 {
   "result": false | true
 }
]

Adding telephone numbers to a mailing list with variables

To add telephone numbers to a mailing list with variables submit a POST request to

https://api.sendpulse.com/sms/numbers/variables

Request parameters:

addressBookId	the ID of the mailing list (int)
phones	the array of phones in json format (find example below)

Array of phone numbers in Json format


{  
   "phones":{  
      "380632631234":[  
         [  
            {  
               "name":"test1",
               "type":"date",
               "value":"2018-10-10"
            },
            {  
               "name":"test2",
               "type":"string",
               "value":"czxczx"
            },
            {  
               "name":"test3",
               "type":"number",
               "value":"123"
            }
         ]
      ],
      "38063333333":[  
         [  
            {  
               "name":"test1",
               "type":"date",
               "value":"2018-10-10"
            },
            {  
               "name":"test2",
               "type":"string",
               "value":"czxczxczx"
            },
            {  
               "name":"test3",
               "type":"number",
               "value":"456"
            }
         ]
      ]
   },
   "addressBookId":1886620
}

Note that value of the "Date" variable must NOT include time, e.g.: " "2018-10-10 23:00:00" is incorrect value format, and "2018-10-10" would be correct.

A sample response:


[
  {
    "result": true,
    "counters": {
    "added": 0,
    "exceptions": 0,
    "exists": 83
    }
  }
]

Changing variables for a phone contact

To change a variable for a phone number, send a post request to:

https://api.sendpulse.com/addressbooks/addressBookId/phones/variable

Sample request parameters:

addressBookId	ID of the address book containing the necessary phone contact with the variable with “name” value
phone	recipient, that will have the variable with “name” value changed to “John”

Array of phone numbers in Json format

{
	"phone": "380931112233",
	"variables": [
		{
			"name" : "name",
			"value" : "John"
		},
		{
			"name" : "number",
			"value": 1
		},
		{
			"name": "date",
			"value" : "2019-02-01"
		},
		{
			"name": "asdasd",
			"value" : "asdasd"
		}
	]
}

*Note: Variable of the string type accepts either numeric values, or values expressing date in the following format: YYYY-MM-DD. "Number" variable accepts only numbers and the “Date” variable only accepts a date in the following format: YYYY-MM-DD. Other formats are not supported. E.g.: a valid date : 2017-01-01, invalid date: 2017-1-1.