API Reference

Welcome to the Data Subs API. Our RESTful architecture allows you to seamlessly integrate VTU purchases, bill payments, KYC verifications, and business registrations directly into your applications.

The API relies on standard HTTP methods, accepts application/json request bodies, and returns JSON-encoded responses.

Base URL

Production: https://datasubs.com.ng
Response Example (Success) 
{
  "status": "success",
  "transaction_ref": "DAT_171000",
  "amount_paid": 280,
  "previous_balance": 5000,
  "new_balance": 4720
}

Authentication

Authenticate your API requests by including your secret API key in the HTTP headers. You can retrieve your API key from the developer section of your dashboard.

Never share your API key publicly or commit it to client-side code (like frontend JavaScript).

HTTP Headers 
Authorization: Token YOUR_API_KEY_HERE
Content-Type: application/json

User Details & Balance

Retrieve your account profile and verify your current wallet balance before making transactions.

GET https://datasubs.com.ng/api/user/
200 Response 
{
  "status": "success",
  "userid": "123",
  "name": "John Doe",
  "balance": "5000.00"
}

Buy Airtime

Top up airtime for any phone number across all networks in Nigeria.

POST https://datasubs.com.ng/api/airtime/
Compatibility: also available at /api/topup/. Also accepts mobile_number and Ported_number as aliases for phone and ported_number, for compatibility with common 3rd-party VTU API formats.
ParameterDescription
network Req Network ID.
1=MTN, 2=AIRTEL, 3=GLO, 4=9MOBILE
phone Req 11-digit phone number.
amount Req Amount to top-up (e.g. 100).
ref Req Your unique transaction reference.
ported_number Opt Set to "true" if number is ported. Default is "false".
Payload (PHP) 
$payload = json_encode([
  "network" => "1", 
  "phone" => "08012345678",
  "amount" => 100, 
  "ref" => "AIR_" . time()
]);
200 Response 
{
  "status": "success",
  "amount_paid": 98.00,
  "transaction_ref": "AIR_171000"
}

Buy Data

Purchase SME, Corporate Gifting, or Direct Data instantly.

POST https://datasubs.com.ng/api/data/
Compatibility: also accepts mobile_number, plan, and Ported_number as aliases for phone, data_plan, and ported_number.
ParameterDescription
network Req Network ID: 1=MTN, 2=AIRTEL, 3=GLO, 4=9MOBILE, 5=SMILE, 6=ALPHA, 7=KIRANI.
Smile Data, Alpha Caller and Kirani Voice are Data plans under networks 5/6/7 - fetch their Plan IDs from the same Data list endpoint below.
phone Req 11-digit phone number.
data_plan Req The specific Plan ID (e.g. 10044). Retrieve from Pricing endpoint.
ref Req Your unique transaction reference.
Payload (PHP) 
$payload = json_encode([
  "network" => "1", 
  "phone" => "08012345678",
  "data_plan" => "10044", 
  "ref" => "DAT_" . time()
]);
200 Response 
{
  "status": "success",
  "amount_paid": 280.00,
  "transaction_ref": "DAT_171000"
}

Verify Electricity Meter

Validate customer details before purchasing electricity token.

POST https://datasubs.com.ng/api/electricity/verify/
Compatibility: also available via GET /ajax/validate_meter_number/?meternumber=&disconame=&mtype=.
Important: the disco table has two different ID columns per row - always send the "eId" value as provider, never a hardcoded number. IDs differ per disco and a few (e.g. Kaduna) do not line up with what you might expect from a simple sequential list.
OLD_TAIL_PLACEHOLDER
ParameterDescription
provider Req Disco eId (e.g. 1 for Ikeja Electric). See the important note above.
meternumber Req The physical meter number.
metertype Req Either "prepaid" or "postpaid".
Payload (PHP) 
$payload = json_encode([
  "provider" => "1", 
  "meternumber" => "12345678901",
  "metertype" => "prepaid"
]);
200 Response 
{
  "status": "success",
  "Customer_Name": "MUSA YUSUF"
}

Pay Electricity Bill

Generate electricity token for verified meters.

POST https://datasubs.com.ng/api/electricity/
Compatibility: also available at /api/billpayment/. Also accepts disco_name, meter_number, and MeterType as aliases for provider, meternumber, and metertype.
Important: use the same "eId" value here as the one used for the verify-meter call above - not any other ID field a provider-list response may include.
ParameterDescription
provider Req Disco eId (same value as the Verify Meter call).
meternumber Req Meter Number.
metertype Req "prepaid" or "postpaid".
amount Req Amount (Minimum usually 1000).
ref Req Unique transaction reference.
200 Response 
{
  "status": "success",
  "plan_description": "Token: 8378-9287...",
  "amount_paid": 1000,
  "customerName": "MUSA YUSUF",
  "customerAddress": "12 Example Street, Kaduna"
}

Verify Cable TV (IUC)

POST https://datasubs.com.ng/api/cabletv/verify/
Compatibility: also available via GET /ajax/validate_iuc/?smart_card_number=&cablename=.
ParameterDescription
provider ReqProvider ID (1=GOTV, 2=DSTV, 3=STARTIMES)
iucnumber ReqCustomer Smartcard Number
200 Response
{
  "status": "success",
  "Customer_Name": "AMINA SULEIMAN"
}

Pay Cable TV

POST https://datasubs.com.ng/api/cabletv/
Compatibility: also available at /api/cablesub/. Also accepts smart_card_number, cablename, and cableplan as aliases for iucnumber, provider, and plan.
ParameterDescription
plan ReqPlan ID (e.g. 128 for GOtv Jinja)
ref ReqUnique reference
Payload (PHP)
$payload = json_encode([
  "provider" => "1", 
  "iucnumber" => "7012345678",
  "plan" => "128", 
  "ref" => "CAB_" . time()
]);

Generate Exam Pin

POST https://datasubs.com.ng/api/exam/
ParameterDescription
provider ReqID (1=WAEC, 2=NECO, 3=NABTEB)
quantity ReqNumber of pins (Min 1, Max 10)
ref ReqUnique reference
200 Response
{
  "status": "success",
  "pin": "123456789012",
  "amount_paid": 3600.00
}

Send Bulk SMS

POST https://datasubs.com.ng/api/sms/

Submit via URL-Encoded Form or Form-Data (Uses $_POST variables).

ParameterDescription
sender_id ReqSender Name
phone_numbers ReqComma separated numbers
message_body ReqMessage content
Payload (PHP)
$post = [
  'sender_id' => 'DATA',
  'phone_numbers' => '0801...,0902...',
  'message_body' => 'Welcome!'
];

Verify Identity (NIN/BVN)

POST https://datasubs.com.ng/api/verify/
ParameterDescription
type Req"bvn" or "nin"
method Req"bvn", "nin", or "phone"
slip_type Opt"information", "standard", "premium"
value ReqThe 11-digit value
200 Response
{
  "status": "success",
  "data": {
     "firstname": "MUSA",
     "nin": "12345678901"
  }
}

CAC Registration

Submit via multipart/form-data for file uploads.

FORM https://datasubs.com.ng/api/cac/
ParameterDescription
type Req"business_name", "company_1m", "ngo"
owner_fullname ReqFull Name of Owner
passport ReqFile Upload (JPG/PNG)
cURL (PHP)
$post = [
  'type' => 'business_name',
  'owner_fullname' => 'John Doe',
  'passport' => new CURLFile('/pass.jpg')
];