API DOCUMENTATION
VERSION 2.O
LAST UPDATED: 1ST FEBRUARY 2023
API DOCUMENTATION
1. GETTING STARTED
1. Create an account on BulkSMSNigeria.com (www.bulksmsnigeria.com/register)
2. Verify at least one of your contacts (i.e., email or phone number).
3. Fund your account with at least 500NGN.
4. Generate an API Token on the API Settings Page (www.bulksmsnigeria.com/app/api-settings)
5. Maintain a minimum balance of 100NGN in the account.
BulkSMSNigeria.com 1
API DOCUMENTATION
2. SENDING AN SMS VIA THE API
ENDPOINT:
• https://www.bulksmsnigeria.com/api/v2/sms (POST)
HEADER PARAMETERS
• 'Accept: application/json',
• 'Content-Type: application/json'
BODY PARAMETERS
from: string | required | max: 11 characters
Preferred sender ID that will display when a message is received. We recommend alphabetic strings
up to a maximum of 11 characters. However, when necessary, you can also make use of
alphanumeric string. We strongly discourage the use of all numeric sender IDs as it could impact
delivery.
to: string | required
Single phone number or a list of comma-separated phone numbers. If you don’t include a country
code, we will default to 234 (Nigeria’s country code).
body: string | required
The message body/content.
api_token: string | required
Can be generated on the API Settings Page => www.bulksmsnigeria.com/app/api-settings
gateway: string | optional | default = ‘direct-refund’
Currently active and available options are:
• ‘direct-refund’ or ‘1’
• ‘direct-corporate’ or ‘2’
• ‘corporate’ or ‘6’
• ‘international’ or ‘7’
• ‘otp’ or ‘8’
append_sender: string | optional | default = ‘hosted’
Sometimes your message gets delivered with a sender ID other than the one you specified. This
happens when you send messages with an unregistered Sender ID, via the corporate route or via
hosted SIM option. In such cases, your recipients might have a hard time figuring out who sent
the message. As such, appending your sender ID to the top of your messages is a good practice,
so that at first glance, your recipients will know who sent the message even if the sender ID is
changed.
Note: We will only append your sender ID to the top of your message if won't increase your page
count and if the sender ID didn't appear in the body of your message.
BulkSMSNigeria.com 2
API DOCUMENTATION
Available options are:
• ‘none’ or ‘1’
• ‘hosted’ or ‘2’
• ‘all’ or ‘3’
Please, note that you need to have a minimum balance of 100NGN in your wallet to make use of
the API.
SAMPLE REQUEST
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://www.bulksmsnigeria.com/api/v2/sms',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"body": "Your one time pass is 4567. Please, don\'t disclose this to anyone.",
"from": "AirtimeNG",
"to": "2348076007676",
"api_token": "PiSeOpDdBmxEgaUV0fLAsNdQ1GvwppHkHEbzDvOn7MMuYjobvkTVy3ioPh1D",
"gateway": "direct-refund"
}',
CURLOPT_HTTPHEADER => array(
'Accept: application/json',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
SAMPLE SUCCESS RESPONSE
{
"data": {
"status": "success",
"message": "Message Sent",
"message_id": "2c28277c-729b-41b9-be79-a1d470a098b4",
"cost": 2.49,
"currency": "NGN",
BulkSMSNigeria.com 3
API DOCUMENTATION
"gateway_used": "direct-refund"
}
}
SAMPLE ERROR RESPONSE
{
"error": {
"message": "Bad request. 'FROM' parameter is missing. Please add a SENDER
ID to your request"
}
}
BulkSMSNigeria.com 4
API DOCUMENTATION
3. GETTING WALLET BALANCE
ENDPOINT:
• https://www.bulksmsnigeria.com/api/v2/balance (GET)
HEADER PARAMETERS
• 'Accept: application/json',
• 'Content-Type: application/json'
BODY PARAMETERS
api_token: string | required
Can be generated on the API Settings Page => www.bulksmsnigeria.com/app/api-settings
SAMPLE REQUEST
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://www.bulksmsnigeria.com/api/v2/balance',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_POSTFIELDS =>'{
"api_token": "PiSeOpDdBmxEgaUV0fLAsNdQ1GvwppHkHEbzDvOn7MMuYjobvkTVy3ioPh1D",
}',
CURLOPT_HTTPHEADER => array(
'Accept: application/json',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
BulkSMSNigeria.com 5
API DOCUMENTATION
SAMPLE SUCCESS RESPONSE
{
"data": {
"status": "success",
"message": "Balance Inquiry Successful"
},
"balance": {
"total_balance": 645834.7100000001,
"universal_wallet": "623428.68",
"sms_wallet": "22405.90",
"sms_bonus": "0.13",
"main_balance": 0,
"volume_bonus": 0,
"promo_bonus": 0
}
}
SAMPLE ERROR RESPONSE
{
"message": "Unauthenticated."
}
BulkSMSNigeria.com 6
API DOCUMENTATION
4. GETTING DELIVERY REPORT
ENDPOINT:
• https://www.bulksmsnigeria.com/api/v2/delivery (GET)
HEADER PARAMETERS
• 'Accept: application/json',
• 'Content-Type: application/json'
BODY PARAMETERS
message_id: string | required
The message_id returned when the message was submitted for delivery.
api_token: string | required
Can be generated on the API Settings Page => www.bulksmsnigeria.com/app/api-settings
SAMPLE REQUEST
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://www.bulksmsnigeria.com/api/v2/delivery',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_POSTFIELDS =>'{
"api_token": "PiSeOpDdBmxEgaUV0fLAsNdQ1GvwppHkHEbzDvOn7MMuYjobvkTVy3ioPh1D",
"message_id": "45e2dae4-933b-4610-ab63-d062b1e9e797",
}',
CURLOPT_HTTPHEADER => array(
'Accept: application/json',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
BulkSMSNigeria.com 7
API DOCUMENTATION
curl_close($curl);
echo $response;
SAMPLE SUCCESS RESPONSE
{
"success": true,
"status": "success",
"message_id": "45e2dae4-933b-4610-ab63-d062b1e9e797",
"data": [
{
"recipient": "2347037770033",
"delivery_status": "delivrd"
}
]
}
SAMPLE ERROR RESPONSE
{
"success": false,
"status": "failed",
"message": "Bad request. The 'message_id' you provided is invalid."
}
BulkSMSNigeria.com 8
