MENU navbar-image

Introduction

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

Authenticating requests

This API is authenticated by sending a parameter api_token in the body of 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' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'to'=> '2347037770033,2349050030090,2347059090000',
            'from'=> 'BulkSMSNG',
            'body'=> 'This is a test message.',
            'gateway'=> '0',
            'append_sender'=> '0',
        ],
        'json' => [
            'api_token' => '{YOUR_API_TOKEN}',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
curl --request POST \
    "https://www.bulksmsnigeria.com/api/v1/sms/create?to=2347037770033%2C2349050030090%2C2347059090000&from=BulkSMSNG&body=This+is+a+test+message.&gateway=0&append_sender=0" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"api_token\": \"{YOUR_API_TOKEN}\"
}"
const url = new URL(
    "https://www.bulksmsnigeria.com/api/v1/sms/create"
);

const params = {
    "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]));

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

let body = {
    "api_token": "{YOUR_API_TOKEN}"
};

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

url = 'https://www.bulksmsnigeria.com/api/v1/sms/create'
payload = {
    "api_token": "{YOUR_API_TOKEN}"
}
params = {
  '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, json=payload, params=params)
response.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

Headers

Content-Type      

Example: application/json

Accept      

Example: application/json

Query Parameters

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). Example: 2347037770033,2349050030090,2347059090000

from   string   

Example: BulkSMSNG

body   string   

Example: This is a test message.

gateway   integer  optional  

Example: 0

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. Example: 0

Body Parameters

api_token   string   

Authentication key. Example: {YOUR_API_TOKEN}

Version 2

API for Version 2

GET api/v2/balance/get

requires authentication

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://www.bulksmsnigeria.com/api/v2/balance/get',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'api_token' => '{YOUR_API_TOKEN}',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
curl --request GET \
    --get "https://www.bulksmsnigeria.com/api/v2/balance/get" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"api_token\": \"{YOUR_API_TOKEN}\"
}"
const url = new URL(
    "https://www.bulksmsnigeria.com/api/v2/balance/get"
);

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

let body = {
    "api_token": "{YOUR_API_TOKEN}"
};

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

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

response = requests.request('GET', url, headers=headers, json=payload)
response.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

Headers

Content-Type      

Example: application/json

Accept      

Example: application/json

Body Parameters

api_token   string   

Authentication key. Example: {YOUR_API_TOKEN}

GET api/v2/balance

requires authentication

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://www.bulksmsnigeria.com/api/v2/balance',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'api_token' => '{YOUR_API_TOKEN}',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
curl --request GET \
    --get "https://www.bulksmsnigeria.com/api/v2/balance" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"api_token\": \"{YOUR_API_TOKEN}\"
}"
const url = new URL(
    "https://www.bulksmsnigeria.com/api/v2/balance"
);

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

let body = {
    "api_token": "{YOUR_API_TOKEN}"
};

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

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

response = requests.request('GET', url, headers=headers, json=payload)
response.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

Headers

Content-Type      

Example: application/json

Accept      

Example: application/json

Body Parameters

api_token   string   

Authentication key. Example: {YOUR_API_TOKEN}

Send Bulk SMS Message.

requires authentication

The endpoint supports POST/GET Methods.

Please, note the "dnd" is deprecated and replaced with "gateway". The gateway parameter will override the "dnd" parameter and subsquent versions of our API won't support the "dnd" parameter.

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://www.bulksmsnigeria.com/api/v2/sms/create',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'to'=> '2347037770033,2349050030090,2347059090000',
            'from'=> 'BulkSMSNG',
            'body'=> 'This is a test message.',
            'gateway'=> '0',
            'append_sender'=> '0',
        ],
        'json' => [
            'api_token' => '{YOUR_API_TOKEN}',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
curl --request POST \
    "https://www.bulksmsnigeria.com/api/v2/sms/create?to=2347037770033%2C2349050030090%2C2347059090000&from=BulkSMSNG&body=This+is+a+test+message.&gateway=0&append_sender=0" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"api_token\": \"{YOUR_API_TOKEN}\"
}"
const url = new URL(
    "https://www.bulksmsnigeria.com/api/v2/sms/create"
);

const params = {
    "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]));

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

let body = {
    "api_token": "{YOUR_API_TOKEN}"
};

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

url = 'https://www.bulksmsnigeria.com/api/v2/sms/create'
payload = {
    "api_token": "{YOUR_API_TOKEN}"
}
params = {
  '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, json=payload, params=params)
response.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

Headers

Content-Type      

Example: application/json

Accept      

Example: application/json

Query Parameters

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). Example: 2347037770033,2349050030090,2347059090000

from   string   

Example: BulkSMSNG

body   string   

Example: This is a test message.

gateway   integer  optional  

Example: 0

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. Example: 0

Body Parameters

api_token   string   

Authentication key. Example: {YOUR_API_TOKEN}

Fetch Delivery Report

requires authentication

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://www.bulksmsnigeria.com/api/v2/delivery',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'message_id'=> 'a22f907b-c5aa-44e4-89e4-06fe253e9cbb',
        ],
        'json' => [
            'api_token' => '{YOUR_API_TOKEN}',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
curl --request GET \
    --get "https://www.bulksmsnigeria.com/api/v2/delivery?message_id=a22f907b-c5aa-44e4-89e4-06fe253e9cbb" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"api_token\": \"{YOUR_API_TOKEN}\"
}"
const url = new URL(
    "https://www.bulksmsnigeria.com/api/v2/delivery"
);

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

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

let body = {
    "api_token": "{YOUR_API_TOKEN}"
};

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

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

response = requests.request('GET', url, headers=headers, json=payload, params=params)
response.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

Headers

Content-Type      

Example: application/json

Accept      

Example: application/json

Query Parameters

message_id   string   

The message_id returned when the message was sent. Example: a22f907b-c5aa-44e4-89e4-06fe253e9cbb

Body Parameters

api_token   string   

Authentication key. Example: {YOUR_API_TOKEN}