NAV -image
php javascript python bash

Introduction

This documentation aims to provide all the information you need to work with our API.

Base URL

https://www.bulksmsnigeria.com/

Authenticating requests

To authenticate requests, include a query parameter api_token in the request.

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve/generate your token by visiting your API Settings Page

Version 1

API for Version 1

Send Bulk SMS Message.

requires authentication

The endpoint supports POST/GET Methods. Send your parameters

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://www.bulksmsnigeria.com/api/v1/sms/create',
    [
        'headers' => [
            'Accept' => 'application/json',
        ],
        'query' => [
            'api_token'=> 'YOUR_API_KEY',
            'to'=> '2347037770033,2349050030090,2347059090000',
            'from'=> 'BulkSMSNG',
            'body'=> 'This is a test message.',
            'gateway'=> '0',
            'append_sender'=> '0',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://www.bulksmsnigeria.com/api/v1/sms/create"
);

let params = {
    "api_token": "YOUR_API_KEY",
    "to": "2347037770033,2349050030090,2347059090000",
    "from": "BulkSMSNG",
    "body": "This is a test message.",
    "gateway": "0",
    "append_sender": "0",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://www.bulksmsnigeria.com/api/v1/sms/create'
params = {
  'api_token': 'YOUR_API_KEY',
  'to': '2347037770033,2349050030090,2347059090000',
  'from': 'BulkSMSNG',
  'body': 'This is a test message.',
  'gateway': '0',
  'append_sender': '0',
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, params=params)
response.json()
curl -X POST \
    "https://www.bulksmsnigeria.com/api/v1/sms/create?api_token=YOUR_API_KEY&to=2347037770033%2C2349050030090%2C2347059090000&from=BulkSMSNG&body=This+is+a+test+message.&gateway=0&append_sender=0" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

Example response (200):


{
0": 200,
"data": {
"status": "success",
"message": "Message Sent",
"message_id": "d0173d84-2f01-4a5f-a0dc-375beea5b806",
"cost": 4.99,
"currency": "NGN",
"gateway_used": "direct_corporate"
}
}

Request      

POST api/v1/sms/create

GET api/v1/sms/create

Query Parameters

api_token  string  
Authentication key.

to  string  
Single phone number or a comma-separated list of phone numbers. If your number do not include a country code, we will default to 234 (Nigeria's country code).

from  string  

body  string  

gateway  integer optional  

append_sender  integer optional  
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. However, we will only append your sender ID to the top of your message if won't increase your page count and also if the sender ID didn't appear in the body of your message. Available options are 'none', 'hosted-sim', 'all'. Defaults to all.

Version 2

API for Version 2

api/v2/balance/get

requires authentication

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://www.bulksmsnigeria.com/api/v2/balance/get',
    [
        'headers' => [
            'Accept' => 'application/json',
        ],
        'query' => [
            'api_token'=> 'YOUR_API_KEY',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://www.bulksmsnigeria.com/api/v2/balance/get"
);

let params = {
    "api_token": "YOUR_API_KEY",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://www.bulksmsnigeria.com/api/v2/balance/get'
params = {
  'api_token': 'YOUR_API_KEY',
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
curl -X GET \
    -G "https://www.bulksmsnigeria.com/api/v2/balance/get?api_token=YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

Example response (200):

{
    "data": {
        "status": "success",
        "message": "Balance Inquiry Successful"
    },
    "balance": {
        "total_balance": 9884094.24,
        "universal_wallet": "9879048.23",
        "sms_wallet": "5046.01",
        "sms_bonus": "0.00",
        "main_balance": 0,
        "volume_bonus": 0,
        "promo_bonus": 0
    }
}

Request      

GET api/v2/balance/get

Query Parameters

api_token  string  
Authentication key.

api/v2/balance

requires authentication

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://www.bulksmsnigeria.com/api/v2/balance',
    [
        'headers' => [
            'Accept' => 'application/json',
        ],
        'query' => [
            'api_token'=> 'YOUR_API_KEY',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://www.bulksmsnigeria.com/api/v2/balance"
);

let params = {
    "api_token": "YOUR_API_KEY",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://www.bulksmsnigeria.com/api/v2/balance'
params = {
  'api_token': 'YOUR_API_KEY',
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
curl -X GET \
    -G "https://www.bulksmsnigeria.com/api/v2/balance?api_token=YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

Example response (200):

{
    "data": {
        "status": "success",
        "message": "Balance Inquiry Successful"
    },
    "balance": {
        "total_balance": 9884094.24,
        "universal_wallet": "9879048.23",
        "sms_wallet": "5046.01",
        "sms_bonus": "0.00",
        "main_balance": 0,
        "volume_bonus": 0,
        "promo_bonus": 0
    }
}

Request      

GET api/v2/balance

Query Parameters

api_token  string  
Authentication key.

Send Bulk SMS Message.

requires authentication

The endpoint supports POST/GET Methods. Send your parameters

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://www.bulksmsnigeria.com/api/v2/sms/create',
    [
        'headers' => [
            'Accept' => 'application/json',
        ],
        'query' => [
            'api_token'=> 'YOUR_API_KEY',
            'to'=> '2347037770033,2349050030090,2347059090000',
            'from'=> 'BulkSMSNG',
            'body'=> 'This is a test message.',
            'gateway'=> '0',
            'append_sender'=> '0',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://www.bulksmsnigeria.com/api/v2/sms/create"
);

let params = {
    "api_token": "YOUR_API_KEY",
    "to": "2347037770033,2349050030090,2347059090000",
    "from": "BulkSMSNG",
    "body": "This is a test message.",
    "gateway": "0",
    "append_sender": "0",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://www.bulksmsnigeria.com/api/v2/sms/create'
params = {
  'api_token': 'YOUR_API_KEY',
  'to': '2347037770033,2349050030090,2347059090000',
  'from': 'BulkSMSNG',
  'body': 'This is a test message.',
  'gateway': '0',
  'append_sender': '0',
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, params=params)
response.json()
curl -X POST \
    "https://www.bulksmsnigeria.com/api/v2/sms/create?api_token=YOUR_API_KEY&to=2347037770033%2C2349050030090%2C2347059090000&from=BulkSMSNG&body=This+is+a+test+message.&gateway=0&append_sender=0" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

Example response (200):


{
0": 200,
"data": {
"status": "success",
"message": "Message Sent",
"message_id": "d0173d84-2f01-4a5f-a0dc-375beea5b806",
"cost": 4.99,
"currency": "NGN",
"gateway_used": "direct_corporate"
}
}

Request      

POST api/v2/sms/create

GET api/v2/sms/create

Query Parameters

api_token  string  
Authentication key.

to  string  
Single phone number or a comma-separated list of phone numbers. If your number do not include a country code, we will default to 234 (Nigeria's country code).

from  string  

body  string  

gateway  integer optional  

append_sender  integer optional  
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. However, we will only append your sender ID to the top of your message if won't increase your page count and also if the sender ID didn't appear in the body of your message. Available options are 'none', 'hosted-sim', 'all'. Defaults to all.

Fetch Delivery Report

requires authentication

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://www.bulksmsnigeria.com/api/v2/delivery',
    [
        'headers' => [
            'Accept' => 'application/json',
        ],
        'query' => [
            'api_token'=> 'YOUR_API_KEY',
            'message_id'=> 'a22f907b-c5aa-44e4-89e4-06fe253e9cbb',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://www.bulksmsnigeria.com/api/v2/delivery"
);

let params = {
    "api_token": "YOUR_API_KEY",
    "message_id": "a22f907b-c5aa-44e4-89e4-06fe253e9cbb",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://www.bulksmsnigeria.com/api/v2/delivery'
params = {
  'api_token': 'YOUR_API_KEY',
  'message_id': 'a22f907b-c5aa-44e4-89e4-06fe253e9cbb',
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
curl -X GET \
    -G "https://www.bulksmsnigeria.com/api/v2/delivery?api_token=YOUR_API_KEY&message_id=a22f907b-c5aa-44e4-89e4-06fe253e9cbb" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

Example response (200):


{
"success": true,
"status": "success",
"message_id": "a22f907b-c5aa-44e4-89e4-06fe253e9cbb",
"data": [
{
"recipient": "2347037770033",
"delivery_status": DELIVRD"
}
]
}

Request      

GET api/v2/delivery

Query Parameters

api_token  string  
Authentication key.

message_id  string  
The message_id returned when the message was sent.

php javascript python bash