SMS Gateway Developers' API

1.0 Introduction

This document describes how to programmatically interact with the SMS server (You should have registered, and created a sub-account that you'll use for accessing this API ).
NEWS!: You can now access the API functions directly on your main account (rather than creating sub-account), to do this, replace the sub-account name with 0, and replace sub-account password with your main account password.
Typical credentials as follows:
sub_account: 001_0
sub_account_pass: MyMainPa$$

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 http://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.

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 URL: http://cheapglobalsms.com/api_v1

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)
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 standard route, 1 means financial route, 2 means corporate route TIPS: TIPS: While using CORPORATE ROUTE helps your budget (economizing by sending through standard channel if the destination has already been found to be unrestrictive). FINANCIAL ROUTE doesn't do such fallback (typically used for OTP/Transactional messages). 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. 		President
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%2Fcheapglobalsms.com%2Fprocess_sms_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
http://cheapglobalsms.com/api_v1?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=send_sms&sender_id=President&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'=>'President',
                    'recipients'=>'08086689567,2348094309926',
                    'message'=>"Hello, there will be a meeting today by 12 noon."
                );
                
                $api_url='http://cheapglobalsms.com/api_v1';

                $ch = curl_init();
                curl_setopt($ch, CURLOPT_URL, $api_url);
                curl_setopt($ch, CURLOPT_POST, true);
                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;
            ?>
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"}
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 URL: http://cheapglobalsms.com/api_v1

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
-4 = UNDELIVERABLE, -3 = EXPIRED, -2 = REJECTED, -1 = FAILED, 0 = PENDING, 1 = ACCEPTED, 2 = DELIVERED
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) President
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 President 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
http://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='http://cheapglobalsms.com/api_v1';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
    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
-4 UNDELIVERABLE The message was undeliverable
-3 EXPIRED Message validity period has expired. (e.g phone off or not in coverage area)
-2 REJECTED The message was rejected. The message was undeliverable.
-1 FAILED An issue occured while attempting to send the SMS.
0 PENDING This message is on queue, to be sent.
1 SENT The message was accepted by the Network server. Awaiting delivery status.
2 DELIVERED Message was delivered to destination.

2.3 Get SMS balance and sub-account information

The following parameters can be sent, through HTTP GET or POST request to the URL: http://cheapglobalsms.com/api_v1

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
http://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='http://cheapglobalsms.com/api_v1';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
    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"}

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

The following parameters can be sent, through HTTP GET or POST request to the URL: http://cheapglobalsms.com/api_v1
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
-4 = UNDELIVERABLE, -3 = EXPIRED, -2 = REJECTED, -1 = FAILED, 0 = PENDING, 1 = ACCEPTED, 2 = DELIVERED
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) President
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.
http://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='http://cheapglobalsms.com/api_v1';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
    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.5 Get SMS delivery statistics

The following parameters can be sent, through HTTP GET or POST request to the URL: http://cheapglobalsms.com/api_v1

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
http://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='http://cheapglobalsms.com/api_v1';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
    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 URL: http://cheapglobalsms.com/api_v1

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
http://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='http://cheapglobalsms.com/api_v1';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
    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 URL: http://cheapglobalsms.com/api_v1

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.
http://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='http://cheapglobalsms.com/api_v1';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
    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 URL: http://cheapglobalsms.com/api_v1

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
http://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='http://cheapglobalsms.com/api_v1';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
    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 URL: http://cheapglobalsms.com/api_v1

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).
http://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='http://cheapglobalsms.com/api_v1';

                $ch = curl_init();
                curl_setopt($ch, CURLOPT_URL, $api_url);
                curl_setopt($ch, CURLOPT_POST, true);
                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 URL: http://cheapglobalsms.com/api_v1

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
http://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='http://cheapglobalsms.com/api_v1';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_POST, true);
    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}
}

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