Developer API

 Back to Blog List 

Share this?



TIP: Always keep your API login information safe. Kindly test the API properly before integration to your project.

Dear Valued Customer,

Our API is easy to integrate and use.

CHECK ACCOUNT BALANCE
Checking your account balance is as follows:

Where:
your_apikey is your account API KEY on your account DashBoard

SENDING A MESSAGE
Sending a message is as follow:

Where:
your_apikey is your account API KEY on your account DashBoard
sender_id is the sender id of your message
recipients_phone_numbers are the phone numbers you are sending your message to. The numbers are seperated by commas (,).
Eg: 08169615492,0803333333,0816666666
message is your the body of your message

sim (Optional) The value is either 0, 1 or 2. If not set is assumed to be 0.
If set to 0 your SMS is sent via the regular route and those on DND are sent via hosted sim
If set to 1 all your SMS are sent via hosted sim irrespective of if they are on DND or not
If set to 2 all your SMS are sent via Corporate Route irrespective of if they are on DND or not
PS: If you have a hosted SIM, yours will be used. If you do not have, our default sim is used. Get your own SIM?

+ RESPONSE: When you succeed in sending a message like that above, you should see a JSON Repsonse like
{"status":"OK","id":"1522059636","amount":"5"}

Where OK means the message was successfully sent and 5 is the number of SMS Units you were charged.
The number (1522059636) is the unique SMS ID. This can be used to check delivery reports of SMS sent.

SCHEDULING A MESSAGE
Scheduling a message allows you set the date and time you want the message sent automatically in future even if you are OFFLINE or SLEEPING.
It has the same features as SENDING A MESSAGE above except with the schedule parameter. The schedule parameter allows you set the date and time.
Where:
your_apikey is your account API KEY on your account DashBoard
sender_id is the sender id of your message
recipients_phone_numbers are the phone numbers you are sending your message to. The numbers are seperated by commas (,).
Eg: 08169615492,0803333333,0816666666
message is your the body of your message

schedule is the date and time you are scheduling your message for.
Kindly note the date and time format Day/Month/Year @ Hour/Minute (am or pm)

sim (Optional) The value is either 0, 1 or 2. If not set is assumed to be 0.
If set to 0 your SMS is sent via the regular route and those on DND are sent via hosted sim
If set to 1 all your SMS are sent via hosted sim irrespective of if they are on DND or not
If set to 2 all your SMS are sent via Corporate Route irrespective of if they are on DND or not
PS: If you have a hosted SIM, yours will be used. If you do not have, our default sim is used. Get your own SIM?

+ RESPONSE: When you succeed in scheduling a message, you should see a JSON Repsonse like
{"status":"OK","id":"1522059636","amount":"5", "duedate":"12/03/2018 @ 11:30 pm"}

Meaning the message has been scheduled for 12/03/2018 @ 11:30 pm and will cost an estimated (5) SMS Units to send.
Kindly ensure you have more than the estimate SMS Units before the scheduled date.
The number (1522059636) is the unique SMS ID. This can be used to check delivery reports of SMS after they are sent.

DELIVERY REPORTS
Checking delivery report on SMS sent is as follows:

Where:
your_apikey is your account API KEY on your account DashBoard
sms_id is the SMS ID returned when you sent the message like 1522059636 in the example above.

+ Each report is seperated by "|" symbol. So after each "|" is a new report. Delivery reports are updated as received so the amount displayed may increase over time. Reports are also available for SMS sent via SIM Hosting.

Example of Report:
| 234703721111113 - DELIVRD / DELIVRD to SIM - MTN - Greenspek - [1.03 Mins]
| 234808661111112 - DELIVRD / DELIVRD to SIM - Sent Via Hosted SIM - [2.46 Mins]
| 23480581111114 - UNDELIV / Unknown Error - globacom - infiniti - [6.03 Mins]

The report shows the Phone Number, Delivery Status (DELIVRD or UNDELIV), the Network it was sent to, the Sender ID (which may be changed due to DND) and the Amount of Time (in Minutes) taken to deliver the message. Cool huh?

CONFIGURATION
It is adviced (NOT compulsory) you use the POST method when submitting instead of GET, especially when sending messages to many numbers. The reason is GET method is limited to a certain lenght of characters which if exceeded will give a (HTTP Error 400 - Bad Request - Request Too Long). The POST method does not give this error.

Sample Code

$c = curl_init("https://www.greenspek.net/ balance.php?apikey=your_apikey");
curl_setopt($c, CURLOPT_CONNECTTIMEOUT,60);
curl_setopt($c, CURLOPT_POST, 1);
curl_setopt ($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HEADER, 0);
curl_setopt($c, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($c, CURLOPT_SSL_VERIFYHOST, false);

$daresponse = curl_exec($c);
curl_close($c);
echo $daresponse;


ERROR CODES
G101 = One or more required fields are empty
G102 = Sender ID not allowed (Should NOT be longer than 11 Characters or less than 4)
G103 = SMS Sending Failed
G104 = Invalid API Key
G105 = Account Balance exhausted
G106 = Insufficent Account Balance for this Message
G107 = Gateway unavailable
G108 = Invalid Schedule date or time format
G109 = Scheduled date has passed
G110 = API Key is empty
G111 = Password is empty
G112 = Recipient is empty or invalid
G113 = Message is empty
G114 = Sender is empty
G115 = SMS ID is empty or invalid
G116 = Message has SPAM related word(s)

+ Remember to UrlEncode your Messages
+ Please note that once set, scheduled messages CANNOT be modified via the API. You have to log into your account to modify it.
+ Ensure your message or sender ID does NOT contain banned keywords.  Read More 
+ Use this format 081-6961-5492 when adding phone numbers to SMS body. DO NOT add numbers like this 08169615492 or it MAY be blocked by the networks

+ All API interactions like sent messages, unsent messages or drafts and scheduled messages are saved to your account by default.
+ Test your SMS length and avoid special characters that may increase your SMS size.  Read More 
+ If you have issues with this API integration, kindly Contact Us


TIP: Always keep your API login information safe. Kindly test the API properly before integration to your project.