Introduction

Base URL: https://www.bulksmsnigeria.com

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"
}
}

Received response:

Request failed with error:

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
    }
}

Received response:

Request failed with error:

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
    }
}

Received response:

Request failed with error:

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"
}
}

Received response:

Request failed with error:

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

from string

Example: BulkSMSNG

body string

Example: This is a test message.

gateway integer optional

Example: 0

append_sender integer optional

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"
}
]
}

Received response:

Request failed with error:

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}