Cheap SMS API

SMS Gateway Developers' API

1.0 Introduction

This document describes how to programatically interact with the SMS server (You should have registered, and created a sub-account that you'll use for accessing this API ).
All requst parameters can be sent, through HTTP GET or POST to the endpoint URL: https://cheapglobalsms.com/api_v1/
NEWS!: You can now access the API functions directly on your main account (rather than creating sub-account), to do this, use your main-account email and password as sub_account and sub_account_pass respectively.

Interaction of this sort might be useful to those desiring to automate SMS sending, fetch the information about sent messages, or pull SMS log into a third party program.
This document is intended to be utilized by technical personnel with programming knowledge; specifically with a working knowledge of HTML forms and JSON.

NOTE: Examine your automation program closely for problems. You are just as responsible for the SMS commands initiated by an automation program as if you had performed the action manually.

1.1 Automation Details

In the following sections, you will find the parameters for using the API and some sample codes.
All API request must be sent to https://cheapglobalsms.com/api_v1/ via HTTP POST or GET method and the response will be returned in a JSON format.

NOTE: If for any request, the error key is present in the JSON response, then the process was NOT successful, and the value of error key is the description of what went wrong.

1.2 Get SMS balance and information

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created. 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be account_info account_info
Filters (Optional Fields)
only_balance Return only the numerical (not json string) value of the balance. Unless there's an authentication error 1
Sample Codes for getting SMS balance
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=account_info 
<?php
    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0R',
        'action'=>'account_info'
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else
    {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else
        {
            $msg="Balance: ".$json['balance'];			
        }
    }
    
    echo $msg;
?>
The response to a successful 'account_info' request will be a JSON Object, containing the sub-account's full information,
Below is a sample successful process's response. 
{"sub_account_id":"1","sub_account":"mysub1","user_id":"1","balance":"1209","notification_email":"example@gmail.com","default_dial_code":"234","timezone_offset":"1","default_sender_id":"tormuto"}
Below is a sample response to a failed process, a JSON Object 
{"error":"Incorrect sub_account name or password","error_code":"4"}

1.3 Update Account Information

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created. 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be update_account_info update_account_info
Optional Fields (At least one of the following must be supplied though)
new_sub_account_name A new sub_account name without the prefix part mysub2
new_notification_email Your valid email address info@example.com
new_default_sender_id A valid fallback value, incase you didn't specify sender-id when sending an sms. At most 11 characters (or at most 14 digits if entirely numerical) MyCompany
new_default_dial_code Whenever you send and sms with to a recipient with the first digit as 0, that 0 will be replaced with this value. Such that 0799... could be interpreted as +1799.. if your default dial code is +1. +1
new_timezone_offset The hours difference between GMT and normal time of your recipients. (This is used for converting values in sms-reports and when scheduling for later delivery) +6:00
Sample Codes for updating account information
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=update_account_info&new_sub_account_name=mysub2&new_default_sender_id=MyCompany&new_default_dial_code=%2B1&new_timezone_offset=%2B6%3A00 
<?php
    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0R',
        'action'=>'update_account_info',
        'new_sub_account_name'=>'mysub2',
        'new_default_sender_id'=>'MyCompany',
        'new_default_dial_code'=>'+1',
        'new_timezone_offset'=>'+6:00',
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else
    {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else {
            $msg=$json['success'];			
        }
    }
    
    echo $msg;
?>
The response to a successful 'update_account_info' request will be a JSON Object, containing a key success with string value, and key updated with the values of updated fields,
Below is a sample successful process's response. 
{"success":"Account info updated","updated":{"sub_account":"mysub2","default_dial_code":"1","timezone_offset":"+6:00","default_sender_id":"MyCompany"}}
Below is a sample response to a failed process, a JSON Object 
{"error":"This operation is only available for sub-accounts","error_code":"11"}

1.4 Add Sub-Account

Same request format and parameter as of above, but here:
action value is add_sub_account, the parameters are compulsory (except new_notification_email).
Also, in the returned response, the new sub-account object's key is 'new_account_info' instead of 'updated'

1.5 Fetch Sub-accounts

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be fetch_sub_accounts fetch_sub_accounts
Filters (Optional Fields)
perpage To fetch large records, it's essential to paginate.
If supplied, maximum is 300 while minimum is 1.		 20
p This is only useful when paginating. It indicates the current page (e.g 1st page) of the record to be fetched. 1
non_empty If set as 1, the results will be only those sub-accounts that has balance 0
Sample Codes for fetching Sub-accounts
A successful request will return a json response having a member key 'records', which contains an array of sub-account objects
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=fetch_sub_accounts&p=1&perpage=50&non_empty=0 
<?php
    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0Rd',
        'action'=>'fetch_sub_accounts',
        'p'=>1,
        'perpage'=>50,
        'non_empty'=>0,
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else {
            //you can now do whatever with the records 
            
            $msg=$json['total']." records, page ".$json['p']." of ".$json['totalpages'];
            
            $msg.= "<br/> <ol>";
            foreach($json['records'] as $row){
                $msg.= "<li>".$row['sub_account'].": ".$row['balance']."credits </li>";
            }
            $msg.= "</ol>";
        }
    }
    
    echo $msg;
?>

1.6 Trasfer balance between main and sub-account

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created. 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be alter_sub_balance alter_sub_balance
amount If this value is positive, credit will be added to the specified sub-account from main account, and reverse case if negative 1000
sub_account_id NOT sub-accout name NOR main user-id prefix. Rather, the sub_account_id itself, as returned during fetch_sub_accounts operation. 120
Optional Fields (At least one of the following must be supplied though)
memo Optional transaction note for reference. This is for invoice xyz
Sample Codes for altering sub-account balance
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=update_account_info&amount=1000&sub_account_id=120&memo=for+invoice+xyz 
<?php
    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0R',
        'action'=>'update_account_info',
        'amount'=>'1000',
        'sub_account_id'=>'120',
        'memo'=>'for invoice xyz',
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else
    {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else {
            $msg=$json['success'];			
        }
    }
    
    echo $msg;
?>
The response to a successful 'alter_sub_balance' request will be a JSON Object, containing a key 'success' with string value,
Below is a sample successful process's response. 
{"success":"1000 credits transferred from main account to 'mysub1'.  New sub-account balance: 1200"}
Below is a sample response to a failed process, a JSON Object 
{"error":"This operation is only available for main accounts","error_code":"11"}

1.7 Fetch Sub-transactions

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be fetch_sub_transactions fetch_sub_transactions
Filters (Optional Fields)
perpage To fetch large records, it's essential to paginate.
If supplied, maximum is 300 while minimum is 1.		 20
p This is only useful when paginating. It indicates the current page (e.g 1st page) of the record to be fetched. 1
search_term If supplied, the records that contains either the sub_account name or transaction detail that 'roughly' matches the supplied value will be returned xyz
start_date The begining filter of date-time of transactions. 2016-04-22 13:45
or
2016-04-22
end_date The end filter of date-time of transactions. 28-04-2016 13:45
or
28-04-2016
Sample Codes for fetching Sub-transactions
A successful request will return a json response having a member key 'records', which contains an array of sub-transaction objects
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=fetch_sub_accounts&p=1&perpage=50&start_date=2022-05-21 
<?php
    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0Rd',
        'action'=>'fetch_sub_transactions',
        'p'=>1,
        'perpage'=>50,
        'start_date'=>'2022-05-21',
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else {
            //you can now do whatever with the records 
            
            $msg=$json['total']." records, page ".$json['p']." of ".$json['totalpages'];
            
            $msg.= "<br/> <ol>";
            foreach($json['records'] as $row){
                $msg.= "<li>".$row['amount'].": ".$row['details']."credits </li>";
            }
            $msg.= "</ol>";
        }
    }
    
    echo $msg;
?>

2.0 SMS Automation

This section describes how you can automatically send SMS, fetch SMS information and delivery statistics, stop / delete SMS / get total units spent or get the balance and other information of the sub-account.

2.1 Sending SMS

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be send_sms send_sms
message The message to be sent. Hello, there will be a meeting today by 12 noon.
recipients The recipient's phone numbers. Multiple numbers can be separated by comma (,).
Any mobile numbers starting with zero will have the zero stripped and replaced with the sub-account's default dial code.
If the mobile number does not start with a zero, the default dial code will not be applied.

E.G if the sub-account's default dial code is '+234',
08086689567,+2348094309926,4478128372838 will be converted to, 2348086689567,2348094309926,4478128372838 		+2348094309926
Optional Fields
type 0 means normal sms, while 1 means flash-message.
If this was not supplied, the message will be assumed to be normal SMS. 		0
unicode 0 means non-unicode sms, while 1 means that the message contains some special characters (e.g chinese, korean,...) that must be preserved (hence the character encoding of the HTTP request is also UTF-8). You can let the system automatically determine the encoding by setting this value as 2
Please note that when a message is in unicode format, the character limits of the messages reduces to 72 characters per page. 		0
route 0 means Optimal Standard Route, 1 means Priority Delivery Route, 2 means Best Pricing Route, 0
sender_id What will appear to the recipient as the sender of the SMS. 3 to 11 characters (or 3 to 14 digits if numeric).
If this was not supplied, the sub-account's default sender_id will be used. 		CGSMS
default_dial_code The number that will replace the leading-zero on the recipient's phone number.
If this was not supplied, the sub-account's default_dial_code will be used. 		234
send_at The message will be on queue, to be sent on the specified date.
If this was not supplied, or if the value is a past date, the message will be sent immediately. 		2016-04-22 13:45
or
2016-04-22
or
13:45
timezone_offset The timezone to be used for send_at.
If this was not supplied, the sub-account's timezone_offset will be used. 		+1
contact_groups Includes all numbers from the supplied contact groups of the sub-account with the recipients default,My Customers
ignore_groups Excludes all numbers that appears in supplied contact groups of the sub-account from the recipients My Customers,My Customers2
contacts A JSON Array of contacts, E.G:
[{"phone":"+2348093216754","firstname":"Pearl"},{"phone":"08086689567","firstname":"Ibukun","lastname":"Oladipo","group_name":"Client","extra_data":"USER001"},{"phone":"+2348094309926","override_message":"Hello, bro. Please be around before 11:00am","override_date_time":"2016-04-22 09:30"}]
** 'phone' is the only compulsory field in a contact, when sending contacts in JSON format.
** If you include 'override_message' in a contact when sending message, it is the override_message that will be sent to that contact instead of the original message.
** If you include 'override_date_time' in a contact, message will rather be sent to the contact at the supplied override_date_time.
** If you include 'extra_data' (maxmum of 60 characters) in a contact when sending message, the value of the extra_data you supplied will be available in the record of the message when you later fetch_sms.
save_as If this is supplied, the recipient phone number(s), will be saved under the group-name; specified as the value of this field, otherwise the numbers will not be saved to contacts default
callback_url If a url-encoded, valid url is specified, the delivery report will be sent as an encoded string of JSON Array, in an HTTP POST request to this supplied URL; under a POST key 'result'. (typically $_POST['result'] in php)
Sample format of the JSON string posted to the callback_url: 
[
                {
                "sms_id":"137072",
                "batch_id":"1_1_1462391634",
                "units":1,
                "pages":1,
                "status":2,
                "status_msg":"DELIVERED",
                "info":"Message delivered to handset",
                "extra_data":""
                },...
            ]
 http%3A%2F%2Fmydomain.com%2Fprocess_callback
NOTE: All duplicate numbers will be automatically removed for you and SMS will be sent to unique recipients only.
Sample codes for sending SMS
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=send_sms&sender_id=CGSMS&message=Hello%2C+there+will+be+a+meeting+today+by+12+noon.&recipients=08086689567,2348094309926 
            <?php
                $post_data=array(
                    'sub_account'=>'001_mysub1',
                    'sub_account_pass'=>'pa55w0Rd',
                    'action'=>'send_sms',
                    'sender_id'=>'CGSMS',
                    'recipients'=>'08086689567,2348094309926',
                    'message'=>"Hello, there will be a meeting today by 12 noon."
                );
                
                $api_url='https://cheapglobalsms.com/api_v1/';

                $ch = curl_init();
                curl_setopt($ch, CURLOPT_URL, $api_url);
                curl_setopt($ch, CURLOPT_POST, true);
				//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
                curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
                curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
                
                $response = curl_exec($ch);
                $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
                if($response_code != 200)$response=curl_error($ch);
                curl_close($ch);

                if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
                else
                {
                    $json=@json_decode($response,true);
                    
                    if($json===null)$msg="INVALID RESPONSE: $response"; 
                    elseif(!empty($json['error']))$msg=$json['error'];
                    else
                    {
                        $msg="SMS sent to ".$json['total']." recipient(s).";
                        $sms_batch_id=$json['batch_id'];
                    }
                }
                
                echo $msg;
            ?>
            
import http.client
import json

payload = {
    "sub_account":"001_mysub1",
    "sub_account_pass":"pa55w0Rd",
    "action":"send_sms",
    "sender_id":"CGSMS",
    "recipients":"08086689567,2348094309926",
    "message":"Hello, there will be a meeting today by 12 noon."
    }

headers = {'content-type': "application/json",}
conn = http.client.HTTPConnection("cheapglobalsms.com")
conn.request("POST", "/api_v1/", json.dumps(payload), headers)

res = conn.getresponse()
data = res.read()
data = data.decode("utf-8")
#print(data)
decoded_data = json.loads(data)

if 'error' in decoded_data:
    print(decoded_data['error'])
else:
    print("Message sent to ",decoded_data['total']," Recipients. Batch ID: ",decoded_data['batch_id']," ACCEPTED LIST:",decoded_data['summary'])

const http = require('http'); 

var payload = {
    "sub_account":"001_mysub1",
    "sub_account_pass":"pa55w0Rd",
    "action":"send_sms",
    "sender_id":"CGSMS",
    "recipients":"08086689567,2348094309926",
    "message":"Hello, there will be a meeting today by 12 noon."
    }
    
sendCGSMSCommand('send_sms',payload,function(responseCode,response){
    if(response['error'])console.log(response['error'])
    else {
        console.log("Message sent to ",response['total']," Recipients. Batch ID: ",response['batch_id']," ACCEPTED LIST:",response['summary'])
    }
});


 /*
    @action: String
    @params: Object containing params
    @callbackFunct(json): the parsed http response get processed in this function        
*/
function sendCGSMSCommand(action,params,callbackFunct){
    if(!params.action)params.action=action;
    var postData = JSON.stringify(params); ;

    var options = {
        hostname: 'cheapglobalsms.com',
        port: 80,
        path: '/api_v1/',
        method: 'POST',
        json:true,
        headers: {
           'Content-Type': 'application/x-www-form-urlencoded',
           'Content-Type': 'application/json',
           'Content-Length': postData.length
        }
    };

    var req = http.request(options, (res) => {
        var str='';
        res.on('data',function(chunk){ str+=chunk; });
        res.on('end',function(){
            try{
                obj=JSON.parse(str);
                callbackFunct(res.statusCode,obj);
            }
            catch(e){
                var err="Error Parsing Response"+e+"\r\n"+str;
                callbackFunct(-1*res.statusCode,err);
                console.log(err)
            }
        });        
    });

    req.on('error', (e) => {
        callbackFunct(-1,e);
        console.error(e);
    });

    req.write(postData);
    req.end();
}
The response to a successful send_sms request will be a JSON Object, containing the batch_id, and the total number of recipient numbers that are successfully parsed. 
    {
        "batch_id":"1_1_1437039374",
        "total":"2",
        "summary":{
            "2348086689567":{"initial_units":2,"pages":1,"pending_review":0},
            "2348094309926":{"initial_units":2,"pages":1,"pending_review":0}
        }
    }
Below is a sample JSON response to a failed process: 
{"error":"insufficient credit","error_code":"1"}

2.2 Fetch SMS information

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be fetch_sms fetch_sms
Filters (Optional Fields)
Only those SMS that matches the specified criteria will be returned.
perpage To fetch large records, it's essential to paginate.
If supplied, maximum is 300 while minimum is 1.		 100
p This is only useful when paginating. It indicates the current page (e.g 1st page) of the record to be fetched. 1
batch_id The batch_id returned from a send_sms action. 1_1_1437039374
sms_ids If the sms_id of the message(s) were already known in advanced, they can be used for filtering. 572,228
stage This can be pending, sent or failed. sent
status The specific (numerical) status of the SMS. Possible statuses and their meanings are
2 = DELIVERED, 1 = ACCEPTED, 0 = PENDING, -1 = FAILED, -2 = REJECTED, -3 = EXPIRED, -4 = UNDELIVERABLE
The stage and status key can not be used together (stage key will be ignored) 		2
type 0 means normal sms, while 1 means flash-message. 0
recipient The recipient number, to which the SMS had been sent, e.g 08094309926 or 2348094309926 or +2348094309926 2348094309926
sender_id 3 to 11 characters (or 3 to 14 digits if numeric) CGSMS
search_term If supplied, the records that contains either the recipient, sender_id or message body that 'roughly' matches the supplied value will be returned CGSMS 2348094309926
start_date The minimum: time sent, or scheduled time, of the messages to be returned. 2016-04-22 13:45
or
2016-04-22
end_date The maximum: time sent, or scheduled time, of the messages to be returned. 28-04-2016 13:45
or
28-04-2016
Sample Codes for fetching SMS records
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=fetch_sms&batch_id=1_1_1437039374 
<?php
    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0Rd',
        'action'=>'fetch_sms',
        'batch_id'=>'1_1_1437039374',
        //'stage'=>'sent'
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else
    {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else
        {
            //you can now do whatever with the records 
            //(e.g check the recipient, fetch the next page or display a message)
            
            $msg=$json['total']." SMS records, page ".$json['p']." of ".$json['totalpages'];
            
            $msg.= "<br/> <ol>";
            foreach($json['records'] as $sms)
            {
                $msg.= "<li>To: ".$sms['recipient']."<br/> ".$sms['message']."</li>";
            }
            $msg.= "</ol>";
        }
    }
    
    echo $msg;
?>
The response to a successful 'fetch_sms' request will be a JSON Object, containing the paging information, and an Array SMS objects,
Below is a sample successful process's response. 
{
    "total":19,"totalpages":1,"p":1,"perpage":100,"timezone_offset":"1",
    "records":[
        {"sms_id":"68",
        "sender":"ibukun",
        "recipient":"2022451175",
        "message":"checking wrong number",
        "sub_account_id":"1",
        "user_id":"1",
        "time_scheduled":"1448224505",
        "batch_id":"1_1_1448224505",
        "status":"-2",
        "type":"0",
        "units":"1",
        "reference":"",
        "time_submitted":"1448224505",
        "time_sent":"1448224505",
        "units_confirmed":"0",
        "locked":"1",
        "info":"Network is forbidden",
        "firstname":"Gotv",
        "lastname":"NUMBER",
        "group_name":"default",
        "status_msg":"REJECTED",
        "submitted_at":"2015-11-22 20:35",
        "scheduled_to":"2015-11-22 20:35",
        "sent_at":"2015-11-22 20:35",
        "extra_data":""
        },
        {"sms_id":"67","sender":"ibukun","recipient":"2348094309926","message":"hello; how're you doing","sub_account_id":"1","user_id":"1","time_scheduled":"1448223878","batch_id":"1_1_1448223878","status":"2","type":"0","units":"2","reference":"","time_submitted":"1448223878","time_sent":"1448223878","units_confirmed":"1","locked":"0","info":"Message delivered to handset","firstname":null,"lastname":null,"group_name":null,"status_msg":"DELIVERED","submitted_at":"2015-11-22 20:24","scheduled_to":"2015-11-22 20:24","sent_at":"2015-11-22 20:24","extra_data":""},
        ...
        ,"filter":{"sub_account_id":"1","batch_id":"","sms_id":"","sms_ids":"","type":"","recipient":"","search_term":"","sender_id":"","stage":"","start_date":"","end_date":"","p":"","perpage":100,"offset":0}
}
For a successfully submitted SMS, the 'status' (in the JSON Object) has following meanings
Code Status Details
2 DELIVERED Message was delivered to destination.
1 SENT The message was accepted by the Network server. Awaiting delivery status.
0 PENDING This message is on queue, to be sent.
-1 FAILED An issue occured while attempting to send the SMS.
-2 REJECTED The message was rejected. The message was undeliverable.
-3 EXPIRED Message validity period has expired. (e.g phone off or not in coverage area)
-4 UNDELIVERABLE The message was undeliverable

2.3 Stop SMS, Delete SMS or Get Total SMS Units Spent

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL
NOTE: Only the SMS that are still on schedule can be stopped.

Input Field Name Description Example Value
sub_account A sub_account name that you have created 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key can be either stop_sms , delete_sms or get_total_units stop_sms
Optional Filters
IMPORTANT: When deleting or stopping SMS, you must specify some kind of filter(s), otherwise your entire sms records will be premanently deleted/stopped
batch_id Typically a batch_id returned from a send_sms action.
An attempt will be made to stop all SMS in this batch. 		1_1_1437039374
sms_ids Typically one or more sms_id from the SMS objects array returned from a fetch_sms action. 572,228
stage This can be pending, sent or failed. sent
status The specific (numerical) status of the SMS. Possible statuses and their meanings are
2 = DELIVERED, 1 = ACCEPTED, 0 = PENDING, -1 = FAILED, -2 = REJECTED, -3 = EXPIRED, -4 = UNDELIVERABLE
The stage and status key can not be used together (stage key will be ignored) 		2
type 0 means normal sms, while 1 means flash-message (flash sms appears temporarily on screen rather than saved-inbox). 0
recipient The recipient number, to which the SMS had been sent, e.g 08094309926 or 2348094309926 or +2348094309926 2348094309926
sender_id 3 to 11 characters (or 3 to 14 digits if numeric) CGSMS
start_date The minimum: time sent, or scheduled time, of the messages to be returned. 2016-04-22 13:45
or
2016-04-22
end_date The maximum: time sent, or scheduled time, of the messages to be returned. 28-04-2016 13:45
or
28-04-2016
Sample Codes for stopping SMS from sending.
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=stop_sms&batch_id=1_1_1437039374 
<?php
    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0R',
        'action'=>'stop_sms',
        'batch_id'=>'1_1_1437039374'
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else
    {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else
        {
            $msg=$json['total']." messages stopped";			
        }
    }
    
    echo $msg;
?>
The response to a successful 'stop_sms' request will be a JSON Object, containing the total number of messages successfully stopped or deleted (as the case may be).
Below is a sample successful process's response. 
{"total":"10"}
Below is a sample response to a failed process, a JSON Object 
{"error":"no record found.","error_code":"10"}

2.4 Get SMS delivery statistics

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be get_delivery_stat get_delivery_stat
batch_id The batch id for consideration 1_1_1462391634
Sample Codes for getting SMS delivery statistics
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=get_delivery_stat&batch_id=1_1_1462391634 
<?php
    $batch_id='1_1_1462391634';
    
    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0R',
        'action'=>'get_delivery_stat',
        'batch_id'=>$batch_id
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else
    {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else
        {
            //you can perform any operation on the available data now
            print_r($json);		
        }
    }
    
    echo $msg;
?>
The response to a successful 'get_delivery_stat' request will be a JSON Object, containing the number of messages and units consumed for each possible sms status, as well as a total (containing summation of units, and messages count in the batch)
Below is a sample successful process's response. 
{"UNDELIVERABLE":{"sms_count":0,"sms_units":0},"EXPIRED":{"sms_count":0,"sms_units":0},"REJECTED":{"sms_count":0,"sms_units":0},"FAILED":{"sms_count":0,"sms_units":0},"PENDING":{"sms_count":13,"sms_units":4},"ACCEPTED":{"sms_count":0,"sms_units":0},"DELIVERED":{"sms_count":0,"sms_units":0},"total":{"sms_count":13,"sms_units":4}}
Below is a sample response to a failed process, a JSON Object 
{"error":"No record found","error_code":11}

3.0 Contacts Manager/Automation

This section describes how you can automatically use the contacts management system to store or backup your contacts, fetch/retrieve your contacts, or even delete contacts

3.1 Save Contacts/Phone Numbers

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be save_contacts save_contacts
Optional/Elective Fields
At least one of 'phone_numbers' or 'contacts' must be supplied.
phone_numbers A string of phone numbers (multiple numbers can be separated by comma)
E.G: 08086689567,+2348094309926,4478128372838
Any mobile numbers starting with zero will have the zero stripped and replaced with the sub-account's default dial code.
+2348094309926
contacts A JSON Array of contacts, E.G:
[{"phone":"08086689567","firstname":"Ibukun","lastname":"Oladipo","group_name":"Client"},{"phone":"+2348094309926","firstname":"Pearl"}]
'phone' is the only compulsory field, when sending contacts in JSON format.
group_name All the supplied numbers/contacts will be saved under this group_name, except those contacts in JSON Array, that also has a group_name defined.

If group_name was not supplied via any means, the contacts will automatically be added under 'default' group_name. 		My Customers
Sample codes for saving contacts
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=save_contacts&group_name=My+Customers&contacts=08086689567,2348094309926 
<?php
    $contacts=array(
        0=>array('phone'=>'08086689567','firstname'=>'Ibukun','lastname'=>'Oladipo','group_name'=>'Client'),
        1=>array('phone'=>'+2348094309926','firstname'=>'Pearl'),
    );

    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0Rd',
        'action'=>'save_contacts',
        'contacts'=>json_encode($contacts),
        'group_name'=>'My Customers',
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else
    {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else
        {
            $msg=$json['total']." contact(s) has been saved.";
        }
    }
    
    echo $msg;
?>
The response to a successful save_contacts request will be a JSON Object, containing the batch_id, and the total number of recipient numbers that are successfully parsed. 
{"total":"2"}
Below is a sample JSON response to a failed process: 
{"error_code":4,"error":"Incorrect sub_account name or password."}

3.2 Fetch Contacts

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be fetch_contacts fetch_contacts
Filters (Optional Fields)
Only those contacts that matches the specified criteria will be returned.
group_name Return only those contacts in this group My Customers
search_term This can be any of phone number, firstname, lastname to find, e.g: 08094309926 or ibukun or 08094309926 ibukun 2348094309926
contact_ids If the specific contact_id(s) to be fetch were already known, it can be used for filtering. 5,7
perpage To fetch large records, it's essential to paginate.
If supplied, maximum value is 300 while minimum is 1.		 100
p This is only useful when paginating. It indicates the current page (e.g 1st page) of the record to be fetched. 1
Sample Codes for fetching contacts.
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=fetch_contacts&group_name=My+Customers 
<?php
    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0Rd',
        'action'=>'fetch_contacts',
        'group_name'=>'My Customers',
        'search_term'=>'ibukun'
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else
    {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else
        {
            //you can now do whatever with the contact records returned
            //(e.g check list the contacts, or even fetch the next page by running the same request with p=1)
            
            $msg=$json['total']." Contacts in total, page ".$json['p']." of ".$json['totalpages'];
            
            $msg.= "<br/> <ol>";
            foreach($json['contacts'] as $contact)
            {
                $msg.= "<li>+".$contact['phone']."<br/> ".$contact['firstname']." ".$contact['lastname']." (".$contact['group_name'].")</li>";
            }
            $msg.= "</ol>";
        }
    }
    
    echo $msg;
?>
The response to a successful 'fetch_contacts' request will be a JSON Object, containing the paging information, and an Array contact objects,
Below is a sample successful process's response. 
{
  "filter":{"user_id":"1","sub_account_id":"1","perpage":10,"group_name":"My Customers","search_term":null,"offset":0},
  "total":2,"p":1,"totalpages":1,
  "records":[{"contact_id":"20","user_id":"1","sub_account_id":"1","phone":"2348086689567","firstname":"","lastname":"","group_name":"My Customers","time":"1445721399"},
  {"contact_id":"21","user_id":"1","sub_account_id":"1","phone":"2348094309926","firstname":"","lastname":"","group_name":"My Customers","time":"1445721399"}
  ]
}

3.3 Get Contact Groups

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be get_contact_groups get_contact_groups
Sample Codes for getting sub-account's contact groups
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=get_contact_groups 
<?php
    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0R',
        'action'=>'get_contact_groups'
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else
    {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else
        {
            $msg="Balance: ".$json['balance'];			
        }
    }
    
    echo $msg;
?>
The response to a successful 'get_contact_groups' request will be a JSON Object, containing 'contact_groups', an object having each contact_group names and their sizes (amount of contact),

Below is a sample successful process's response. 
{"contact_groups":{"My Customers":"2","default":"4"}}

3.4 Delete Contacts

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be delete_contacts delete_contacts
Filters (Optional Fields)
ALL those contacts that matches the specified criteria will be deleted.
group_name Return only those contacts in this group My Customers
search_term This can be any of phone number, firstname, lastname to find, e.g: 08094309926 or ibukun or 08094309926 ibukun 2348094309926
contact_ids Typically one or more contact_id, from the array of contact objects returned from a fetch_contacts action. 5,7
Sample Codes for deleting contact(s).
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=delete_contacts&contact_ids=5%2C7 
            <?php
                $post_data=array(
                    'sub_account'=>'001_mysub1',
                    'sub_account_pass'=>'pa55w0R',
                    'action'=>'delete_contacts',
                    'contact_ids'=>'5,7'
                );
                
                $api_url='https://cheapglobalsms.com/api_v1/';

                $ch = curl_init();
                curl_setopt($ch, CURLOPT_URL, $api_url);
                curl_setopt($ch, CURLOPT_POST, true);
				//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
                curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
                curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
                
                $response = curl_exec($ch);
                $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
                if($response_code != 200)$response=curl_error($ch);
                curl_close($ch);

                if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
                else
                {
                    $json=@json_decode($response,true);
                    
                    if($json===null)$msg="INVALID RESPONSE: $response"; 
                    elseif(!empty($json['error']))$msg=$json['error'];
                    else
                    {
                        $msg="Total deleted contacts: ".$json['total'];			
                    }
                }
                
                echo $msg;
            ?>
The response to a successful 'delete_contacts' request will be a JSON Object, containing the total number of deleted contacts.
Below is a sample successful process's response. 
{"total":"4"}
Below is a sample response to a failed process, a JSON Object 
{"error":"No contact_ids supplied to be deleted","error_code":"7"}

4.0 Campaigns (Receiving & Processing SMS)

This section describes the structure of HTTP POST request that gets posted to your supplied callback_url, each time an SMS is sent to the number/keywords that you are listening on

4.1 Callback Data

The following parameters will be sent, through HTTP POST request to the callback_url that you specify

HTTP POST KEY Description Example Value
sender The phone number that sent the SMS (without the leading +) 2348093216754
recipient Your phone number (that has been configured here), to which the SMS has been sent 2348030000000 or 23451007
campaign_id ID of the campaign that captured/intercept this message for you 121
message The full content of the message sent STOP SERVICE1 James Richard
pages Number of SMS pages covered by this message 1
keyword The keyword that you specified while setting up the campaign STOP
clean_message The remaining part of the message, after the keyword James Richard

4.2 Fetching or Deleting Inbox Message

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be fetch_inbox or delete_inbox fetch_inbox
Filters (Optional Fields)
When fetching messages, only those messages that matches the specified criteria will be returned.
IMPORTANT: When deleting or stopping SMS, you must specify some kind of filter(s), otherwise your entire sms records will be permanently deleted/stopped
perpage To fetch large records, it's essential to paginate.
If supplied, maximum is 300 while minimum is 1.		 100
p This is only useful when paginating. It indicates the current page (e.g 1st page) of the record to be fetched. 1
campaign_id The campaign_id that captured the messages. 1411
message_ids If the message_id of the message(s) were already known in advanced, they can be used for filtering. 572,228
keyword This keywords that captured the messages STOP
recipient The number you configured, to which the message was sent, e.g 08094309926 or 2348094309926 or +2348094309926 2348094309926
sender The number that sends in the message 2348094309923
search_term If supplied, the records that contains either the recipient, sender or message body that 'roughly' matches the supplied value will be returned STOP SERVICE1
start_date The minimum time of the messages to be returned. 2016-04-22 13:45
or
2016-04-22
end_date The maximum time of the messages to be returned. 28-04-2016 13:45
or
28-04-2016
Sample Codes for fetching inbox messages
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=fetch_inbox&campaign_id=1411 
<?php
    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0Rd',
        'action'=>'fetch_inbox',
        'batch_id'=>'1411',
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else
    {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else
        {
            //you can now do whatever with the records 
            //(e.g check the sender, fetch the next page or display a message)
            
            $msg=$json['total']." messages, page ".$json['p']." of ".$json['totalpages'];
            
            $msg.= "<br/> <ol>";
            foreach($json['records'] as $message)
            {
                $msg.= "<li>From: ".$sms['sender']."<br/> ".$sms['message']."</li>";
            }
            $msg.= "</ol>";
        }
    }
    
    echo $msg;
?>
The response to a successful 'fetch_inbox' request will be a JSON Object, containing the paging information, and an Array SMS objects,
Below is a sample successful process's response. 
{
    "total":19,"totalpages":1,"p":1,"perpage":100,"timezone_offset":"1",
    "records":[
        {"sms_id":"68",
        "sender":"ibukun",
        "recipient":"2022451175",
        "message":"checking wrong number",
        "sub_account_id":"1",
        "user_id":"1",
        "time_scheduled":"1448224505",
        "batch_id":"1_1_1448224505",
        "status":"-2",
        "type":"0",
        "units":"1",
        "reference":"",
        "time_submitted":"1448224505",
        "time_sent":"1448224505",
        "units_confirmed":"0",
        "locked":"1",
        "info":"Network is forbidden",
        "firstname":"Gotv",
        "lastname":"NUMBER",
        "group_name":"default",
        "status_msg":"REJECTED",
        "submitted_at":"2015-11-22 20:35",
        "scheduled_to":"2015-11-22 20:35",
        "sent_at":"2015-11-22 20:35",
        "extra_data":""
        },
        {"sms_id":"67","sender":"ibukun","recipient":"2348094309926","message":"hello; how're you doing","sub_account_id":"1","user_id":"1","time_scheduled":"1448223878","batch_id":"1_1_1448223878","status":"2","type":"0","units":"2","reference":"","time_submitted":"1448223878","time_sent":"1448223878","units_confirmed":"1","locked":"0","info":"Message delivered to handset","firstname":null,"lastname":null,"group_name":null,"status_msg":"DELIVERED","submitted_at":"2015-11-22 20:24","scheduled_to":"2015-11-22 20:24","sent_at":"2015-11-22 20:24","extra_data":""},
        ...
        ,"filter":{"sub_account_id":"1","batch_id":"","sms_id":"","sms_ids":"","type":"","recipient":"","search_term":"","sender":"","stage":"","start_date":"","end_date":"","p":"","perpage":100,"offset":0}
}

4.3 Fetch Available Virtual Numbers

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be fetch_virtual_numbers fetch_virtual_numbers
Filters (Optional Fields)
Only those virtual_numbers that matches the specified criteria will be returned.
country Return only those virtual numbers for this country code PL
perpage To fetch large records, it's essential to paginate.
If supplied, maximum value is 300 while minimum is 1.		 100
p This is only useful when paginating. It indicates the current page (e.g 1st page) of the record to be fetched. 1
Sample Codes for fetching virtual_numbers.
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=fetch_virtual_numbers&country=PL 
<?php
    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0Rd',
        'action'=>'fetch_virtual_numbers',
        'country'=>'PL',
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else
    {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else
        {
            //you can now do whatever with the virtual_number records returned
            //(e.g acquire the virtual number, or even fetch the next page by running the same request with p=1)
            
            $msg=$json['total']." Virtual Numbers in total, page ".$json['p']." of ".$json['totalpages'];
            
            $msg.= "<br/> <ol>";
            foreach($json['records'] as $virtual_number)
            {
                $msg.= "<li>+".$virtual_number['number']." :: ".$virtual_number['first_month_total_credits']."  credits </li>";
            }
            $msg.= "</ol>";
        }
    }
    
    echo $msg;
?>
The response to a successful 'fetch_virtual_numbers' request will be a JSON Object, containing the paging information, and an Array virtual number objects,
Below is a sample successful process's response. 
{
    "total": 1250,
    "totalpages": 63,
    "p": 1,
    "perpage": 20,
    "timezone_offset": "1",
    "records": [
        {
            "number": "48664078775",
            "number_key": "CE2B0D0F8E34FBF3B0EB915AD09433B4",
            "country": "Poland",
            "country_code": "PL",
            "country_code3": "POL",
            "type": "VIRTUAL_LONG_NUMBER",
            "instant_automated_setup": false,
            "monthly_renewal_credits": 2070,
            "first_month_credits": 2070,
            "first_month_setup_credits": 2070,
            "first_month_total_credits": 4140
        },
        {
            "number": "48664078779",
            "number_key": "6DFC8D8CCD29F8441AB5EDF88658BC0A",
            "country": "Poland",
            "country_code": "PL",
            "country_code3": "POL",
            "type": "VIRTUAL_LONG_NUMBER",
            "instant_automated_setup": false,
            "monthly_renewal_credits": 2070,
            "first_month_credits": 2070,
            "first_month_setup_credits": 2070,
            "first_month_total_credits": 4140
        }
    ],
    "filter": {
        "sub_account_id": "1",
        "user_id": "1",
        "country": "PL",
        "p": "",
        "perpage": 20,
        "offset": 0
    }
}

4.4 Get Virtual Number

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created. 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be acquire_number acquire_number
number The virtual number that you want to acquire. 48664078775
country The two-letter country-code of this virtual number. PL
number_key The number_key for this virtual number (obtained from the fetch_virtual_numbers request). CE2B0D0F8E34FBF3B0EB915AD09433B4
Sample Codes for buying a new virtual number
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=acquire_number&number=48664078775&country=PL&number_key=CE2B0D0F8E34FBF3B0EB915AD09433B4 
<?php
    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0R',
        'action'=>'acquire_number',
		'number'=>'48664078775',
		'country'=>'PL',
		'number_key'=>'CE2B0D0F8E34FBF3B0EB915AD09433B4',
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else
    {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else
        {
            $msg=$json['success'];			
        }
    }
    
    echo $msg;
?>
The response to a successful 'acquire_number' request will be a JSON Object, containing the sub-account's full information,
Below is a sample successful process's response. 
{"success":"You've successfully acquire +48664078775 for a month. Configure it now"}

4.5 Fetch Campaigns

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be fetch_campaigns fetch_campaigns
Filters (Optional Fields)
country_code Return only your campaigns with virtual numbers for this country code PL
search_term If supplied, only the campaigns with virtual numbers that matches this filter will be returned. 48664078775
status Filter by numerical status
0=>PAUSED, 1=>ACTIVE, -4=>EXPIRED 		1
perpage To fetch large records, it's essential to paginate.
If supplied, maximum is 300 while minimum is 1.		 20
p This is only useful when paginating. It indicates the current page (e.g 1st page) of the record to be fetched. 1
Sample Codes for fetching campaigns
A successful request will return a json response having a member key 'records', which contains an array of sub-account objects
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=fetch_campaigns&country_code=PL 
<?php
    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0Rd',
        'action'=>'fetch_campaigns',
        'country_code'=>'PL'
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else {
            //you can now do whatever with the records 
            
            $msg=$json['total']." records, page ".$json['p']." of ".$json['totalpages'];
            
            $msg.= "<br/> <ol>";
            foreach($json['records'] as $row){
                $msg.= "<li>ID: ".$row['campaign_id']." :: Virtual Number: +".$row['recipient']." </li>";
            }
            $msg.= "</ol>";
        }
    }
    
    echo $msg;
?>

4.6 Edit Campaign

The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created. 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be edit_campaign edit_campaign
campaign_id The campaign ID obtained from fetch_campaigns 123
Optional Fields (At least one of the following must be supplied though)
callback_url The endpoint where you remotely handle the HTTP POST request (as described in ) whenever someone sent an SMS to our line. http%3A%2F%2Fmydomain.com%2Fprocess_callback
add_contacts This specifies a list of contact groups. If a line send an sms to your virtual number; the line will be added to each of these contact groups. MyContactGroup1,MyContactGroup7
delete_contacts This specifies a list of contact groups. If a line send an sms to your virtual number; and the line exists in any of this contact groups; the contact will be deleted from the group. MyContactGroup1,MyContactGroup7
update_contact_firstname This specifies a list of contact groups. If a line send an sms to your virtual number; and the line exists in any of this contact groups; firstname of this contact will be replaced by the message of the text received. MyContactGroup1,MyContactGroup7
update_contact_lastname This specifies a list of contact groups. If a line send an sms to your virtual number; and the line exists in any of this contact groups; lastname of this contact will be replaced by the message of the text received. MyContactGroup1,MyContactGroup7
update_contact_group_name This specifies a list of contact groups. If a line send an sms to your virtual number; and the line exists in any of this contact groups; this contact will be moved to the group name labelled by the text received. MyContactGroup1,MyContactGroup7
auto_renew Options are 0 and 1, When it's 1, this virtual number will be renewed upon expiry, from your balance. 1
Sample Codes for updating campaign information
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=edit_campaign&campaign_id=123&add_contacts=MyContactGroup1 
<?php
    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0R',
        'action'=>'edit_campaign',
		'campaign_id'=>'123',
		'add_contacts'=>'MyContactGroup1',
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else
    {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else {
            $msg=$json['success'];			
        }
    }
    
    echo $msg;
?>
The response to a successful 'edit_campaign' request will be a JSON Object, containing a key success with string value, and key updated with the values of updated fields,
Below is a sample successful process's response. 
{"success":"Your campaign as been successfully updated"}

4.7 Rectify Incomplete Virtual-Number Configuration

For some countries, when you buy virtual number; its setup requires a manual approval process with the operator.
For these numbers, the extra_data key will not contain the configurationKey when fetched with the fetch_campaigns
You may use this call, to attempt its finalization, in case the manual approval had been done.
The following parameters can be sent, through HTTP GET or POST request to the API endpoint URL

Input Field Name Description Example Value
sub_account A sub_account name that you have created. 001_mysub1
sub_account_pass Sub account password pa55w0Rd
action The value for this key must be rectify_campaign rectify_campaign
number The virtual number with incomplete configuration, that you want to rectify. 48664078775
Sample Codes for rectifying a campaign's virtual number configuration.
https://cheapglobalsms.com/api_v1/?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=rectify_campaign&number=48664078775 
<?php
    $post_data=array(
        'sub_account'=>'001_mysub1',
        'sub_account_pass'=>'pa55w0R',
        'action'=>'rectify_campaign',
		'number'=>'48664078775',
    );
    
    $api_url='https://cheapglobalsms.com/api_v1/';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
	//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if($response_code != 200)$response=curl_error($ch);
    curl_close($ch);

    if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
    else
    {
        $json=@json_decode($response,true);
        
        if($json===null)$msg="INVALID RESPONSE: $response"; 
        elseif(!empty($json['error']))$msg=$json['error'];
        else
        {
            $msg=$json['success'];			
        }
    }
    
    echo $msg;
?>
The response to a successful 'rectify_campaign' request will be a JSON Object, containing the sub-account's full information,
Below is a sample successful process's response. 
{"success":"Configuration successful finalized for +48664078775"}

Disclaimer

The Author accepts no responsibility for damages to persons, property or data incurred through the use or misuse of these API and scripts. To the maximum extent permitted by law, in no event shall the Author be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use or inability to use this API, even if the Author has been advised of the possibility of such damages.
This product is supplied as-is, with no warranties express or implied. Use this documentation at your own risk.

Error Codes and Descriptions

Error Code Description
1 sub_account not supplied
2 sub_account_pass not supplied
3 action not supplied
4 Incorrect sub_account name or password
5 The sub-account is currently disabled
6 Invalid action
7 missing request parameter
8 incorrect request parameter
9 confusing request parameters
10 no record found
11 operation failed
12 insufficient balance