Bulk SMS API Nigeria

Endpoints

Request Parameters

Code Examples

curl -X POST https://www.bulksmsnigeria.com/api/v2/sms \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "from": "YourCompany",
    "to": "2347012345678,2348012345678",
    "body": "Hello from BulkSMS Nigeria API! Welcome to our service.",
    "gateway": "direct-refund"
  }'

<?php
$apiToken = 'YOUR_API_TOKEN';
$url = 'https://www.bulksmsnigeria.com/api/v2/sms';

$data = [
    'from' => 'YourCompany',
    'to' => '2347012345678,2348012345678',
    'body' => 'Hello from BulkSMS Nigeria API!',
    'gateway' => 'direct-refund'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiToken,
    'Content-Type: application/json',
    'Accept: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

import requests
import json

api_token = 'YOUR_API_TOKEN'
url = 'https://www.bulksmsnigeria.com/api/v2/sms'

headers = {
    'Authorization': f'Bearer {api_token}',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}

data = {
    'from': 'YourCompany',
    'to': '2347012345678,2348012345678',
    'body': 'Hello from BulkSMS Nigeria API!',
    'gateway': 'direct-refund'
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

const apiToken = 'YOUR_API_TOKEN';
const url = 'https://www.bulksmsnigeria.com/api/v2/sms';

const data = {
    from: 'YourCompany',
    to: '2347012345678,2348012345678',
    body: 'Hello from BulkSMS Nigeria API!',
    gateway: 'direct-refund'
};

fetch(url, {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${apiToken}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json'
    },
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.error('Error:', error));

Success Response

{
  "status": "success",
  "code": "BSNG-0000",
  "message": "Message sent successfully",
  "data": {
    "message_id": "a22f907b-c5aa-44e4-89e4-06fe253e9cbb",
    "cost": 5.00,
    "currency": "NGN",
    "recipients_count": 2,
    "gateway_used": "direct-refund",
    "unicode": false,
    "page_count": 1
  }
}

Error Responses

Errors use the same envelope with "status": "error", a BSNG-XXXX code and a matching HTTP status. None of the errors below send the message or charge your wallet, so fix the request rather than retrying it unchanged.

{
  "status": "error",
  "code": "BSNG-2012",
  "error": {
    "message": "Duplicate message. An identical message was sent to the same recipients within the last minute, so this one was not sent and you were not charged.",
    "code": "BSNG-2012",
    "description": "Duplicate message"
  }
}

The full list of error codes is in the API documentation in your dashboard.

Endpoint

Example Request

curl -X GET https://www.bulksmsnigeria.com/api/v2/balance \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Success Response

{
  "data": {
    "status": "success",
    "message": "Balance Inquiry Successful"
  },
  "balance": {
    "total_balance": 9884.24,
    "universal_wallet": "9879.23",
    "sms_wallet": "5.01",
    "sms_bonus": "0.00"
  }
}

Endpoint

Parameters

Example Request

curl -X GET "https://www.bulksmsnigeria.com/api/v2/delivery-reports?message_id=YOUR_MESSAGE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Success Response

{
  "status": "success",
  "code": "BSNG-0000",
  "message": "Delivery report retrieved",
  "data": {
    "message_id": "a22f907b-c5aa-44e4-89e4-06fe253e9cbb",
    "summary": {"total": 3, "delivered": 2, "pending": 1, "failed": 0},
    "reports": [
      {"recipient": "2347037770033", "delivery_status": "delivrd"},
      {"recipient": "2348012345678", "delivery_status": "delivrd"},
      {"recipient": "2349050030090", "delivery_status": "sent awaiting status"}
    ],
    "pagination": {"current_page": 1, "per_page": 100, "total": 3, "last_page": 1}
  }
}

Endpoint

Example Request

curl -X GET https://www.bulksmsnigeria.com/api/v2/sender-ids \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Success Response

{
  "status": "success",
  "code": "BSNG-0000",
  "message": "Sender IDs retrieved",
  "data": {
    "sender_ids": [
      {"sender_id": "MyBrand", "status": "approved", "purpose": "Transactional alerts", "approved_at": "2026-01-15 09:30:00", "rejection_reason": null}
    ],
    "total": 1
  }
}

Endpoint

Example Request

curl -X GET https://www.bulksmsnigeria.com/api/v2/account \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Success Response

{
  "status": "success",
  "code": "BSNG-0000",
  "message": "Account information retrieved",
  "data": {
    "user_id": "0f8e2a64-1bbb-4f3e-9c0d-5a3a1c2d4e5f",
    "email": "dev@example.com",
    "name": "Ada Developer",
    "account_status": "active",
    "verification_level": "verified",
    "balance": 10250.50,
    "currency": "NGN",
    "created_at": "2025-11-02 08:14:33"
  }
}