API Explain

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.
API DOCUMENTATION
Available options are:

• ‘none’ or ‘1’
• ‘hosted’ or ‘2’
• ‘all’ or ‘3’
callback_url: string | optional

If your request includes a callback_url, we will push delivery reports/statuses to your server as
soon as we received them. The callback URL should be an absolute URL, for example:
‘https://www.airtimenigeria.com/api/report/sms’
customer_reference: string | optional

Unique internal identifier to enable your system easily map delivery reportfor easier delivery report
mapping.
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",
"customer_reference": "HXYSJWKKSLOX",
"callback_url": "https://www.airtimenigeria.com/api/reports/sms",
}',
CURLOPT_HTTPHEADER => array(
'Accept: application/json',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
API DOCUMENTATION
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",
"gateway_used": "direct-refund",
}
}
SAMPLE ERROR RESPONSE

{
"error": {
"message": "Bad request. 'FROM' parameter is missing. Please add a SENDER
ID to your request"
}
}
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;
API DOCUMENTATION

{
"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."
}
API DOCUMENTATION
4. GETTING DELIVERY REPORT
VIA PROVIDED CALLBACK_URL: (GET)

{
"recipient": true,
"delivery_status": "delivrd",
"cutomer_reference": "HXJISI6OE7LS",
"callback_url": "https://webhook.site/378919af-f9e0-47d3-9df1-fc7bbc2ff305",
"message_id": "edd0e76f-80f2-4c49-8775-13767a08f904",
"data": {
"recipient": "2347037770033",
"delivery_status": "delivrd",
"message_id": "edd0e76f-80f2-4c49-8775-13767a08f904",
"cutomer_reference": "HXJISI6OE7LS"
}
}

API Explain

Uploaded by

Copyright:

Available Formats

API Explain

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

API Explain

Uploaded by

Copyright:

Available Formats

API DOCUMENTATION

LAST UPDATED: 1ST FEBRUARY 2023

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.

2. SENDING AN SMS VIA THE API

to: string | required

body: string | required

api_token: string | required

gateway: string | optional | default = ‘direct-refund’

append_sender: string | optional | default = ‘hosted’

Available options are:

callback_url: string | optional

customer_reference: string | optional

SAMPLE SUCCESS RESPONSE

SAMPLE ERROR RESPONSE

3. GETTING WALLET BALANCE

SAMPLE SUCCESS RESPONSE

SAMPLE ERROR RESPONSE

4. GETTING DELIVERY REPORT

VIA PROVIDED CALLBACK_URL: (GET)

SAMPLE SUCCESS RESPONSE

You might also like