API Reference Manual

Welcome to the AsadHub Developer API. Integrate real-time instant Airtime top-up, SME & Direct Data bundles, Cable TV bouquet subscriptions (DStv, GOtv, StarTimes), and Electricity tokens (Prepaid & Postpaid DisCos) into your platforms.

Authentication

Every request requires authentication via your private API Key or a Bearer Token generated on your user account.

X-API-Key: YOUR_API_KEY

Alternatively, pass the standard Bearer header:

Authorization: Bearer YOUR_API_KEY

Security Notice: Keep your API key secure. Never commit it to client-side code (browsers or public mobile apps). Regenerate it immediately from your profile dashboard if compromised.

Fetch User Profile & Wallet Details

GET POST /api/user

Returns the authenticated user's account info, verification status, dedicated virtual account details, and full wallet breakdown.

curl -X GET https://asadhub.com.ng/docs/api/user \
  -H "X-API-Key: YOUR_API_KEY"

Fetch Wallet Balance

GET POST /api/user?action=balance

Lightweight endpoint for high-frequency balance checks prior to initiating transaction requests.

curl -X GET https://asadhub.com.ng/docs/api/user?action=balance \
  -H "X-API-Key: YOUR_API_KEY"

Buy Airtime

POST /api/airtime

Top up VTU airtime for MTN, Glo, Airtel, or 9mobile instantly.

Parameters

Field	Type	Required	Description
`network`	String	Yes	`MTN`, `GLO`, `AIRTEL`, or `9MOBILE`
`phone`	String	Yes	11-digit Nigerian recipient phone number
`amount`	Float	Yes	Amount in NGN (min ₦50)
`bypass_ported`	Integer	No	Set `1` to bypass ported number checks

Example Request

curl -X POST https://asadhub.com.ng/docs/api/airtime \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "MTN",
    "phone": "08031234567",
    "amount": 500
  }'

Fetch Data Plans

GET /api/data-plans

Get the live list of available data plans, pricing, codes, and validity.

curl -X GET "https://asadhub.com.ng/docs/api/data-plans?network=MTN" \
  -H "X-API-Key: YOUR_API_KEY"

Buy Data Bundle

POST /api/data

Purchase SME, Gifting, or Corporate data bundles.

Parameters

Field	Type	Required	Description
`network`	String	Yes	`MTN`, `GLO`, `AIRTEL`, or `9MOBILE`
`phone`	String	Yes	11-digit Nigerian recipient phone number
`plan_code`	String	Yes	Plan code from `/api/data-plans`

Example Request

curl -X POST https://asadhub.com.ng/docs/api/data \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "MTN",
    "phone": "08031234567",
    "plan_code": "MTN_SME_1GB"
  }'

Fetch Cable TV Plans

GET /api/cable-plans

Retrieve all active subscription packages for DStv, GOtv, and StarTimes.

Query Parameters (Optional)

provider: Filter by DSTV, GOTV, or STARTIMES

curl -X GET "https://asadhub.com.ng/docs/api/cable-plans?provider=GOTV" \
  -H "X-API-Key: YOUR_API_KEY"

Validate Smartcard / IUC Number

GET POST /api/cable/validate

Verify customer name and subscription status on a smartcard or IUC number before processing payment.

Parameters

Field	Type	Required	Description
`decoder_number`	String	Yes	Smartcard / IUC number
`provider`	String	Yes	`DSTV`, `GOTV`, or `STARTIMES`

curl -X POST https://asadhub.com.ng/docs/api/cable/validate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decoder_number": "2019482710",
    "provider": "GOTV"
  }'

Pay Cable TV Subscription

POST /api/cable

Instantly renew or upgrade a cable TV bouquet.

Parameters

Field	Type	Required	Description
`decoder_number`	String	Yes	Smartcard / IUC number
`plan_code`	String	Yes	Package code from `/api/cable-plans` (e.g. `GOTV_MAX`)
`phone`	String	No	Customer phone number

curl -X POST https://asadhub.com.ng/docs/api/cable \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decoder_number": "2019482710",
    "plan_code": "GOTV_MAX",
    "phone": "08012345678"
  }'

Fetch Electricity DisCos

GET /api/electricity/providers

Returns the complete list of supported Electricity Distribution Companies across Nigeria.

curl -X GET https://asadhub.com.ng/docs/api/electricity/providers \
  -H "X-API-Key: YOUR_API_KEY"

Validate Meter Number

GET POST /api/electricity/validate

Verify customer identity, address, and meter validity prior to recharging.

Parameters

Field	Type	Required	Description
`meter_number`	String	Yes	Prepaid or Postpaid meter number
`disco`	String	Yes	DisCo code (e.g. `IKEDC`, `EKEDC`, `AEDC`, `IBEDC`, `EEDC`, `KEDCO`, `PHED`)
`meter_type`	String	No	`prepaid` (default) or `postpaid`

curl -X POST https://asadhub.com.ng/docs/api/electricity/validate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "meter_number": "01429817462",
    "disco": "IKEDC",
    "meter_type": "prepaid"
  }'

Pay Electricity Bill / Buy Token

POST /api/electricity

Purchase prepaid electricity recharge tokens or pay postpaid utility bills.

Parameters

Field	Type	Required	Description
`meter_number`	String	Yes	Target meter number
`disco`	String	Yes	DisCo code (e.g. `IKEDC`, `EKEDC`, `AEDC`, `IBEDC`, `EEDC`, `KEDCO`, `PHED`)
`amount`	Float	Yes	Amount in NGN (min ₦500)
`meter_type`	String	No	`prepaid` (default) or `postpaid`
`phone`	String	No	Phone number for token SMS

curl -X POST https://asadhub.com.ng/docs/api/electricity \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "meter_number": "01429817462",
    "disco": "IKEDC",
    "amount": 2000,
    "meter_type": "prepaid",
    "phone": "08012345678"
  }'

NIN Verification & Slip Generation

Verify National Identification Number (NIN) by 11-digit NIN, linked phone number, demographic search (Name & DOB), or 16-character Virtual NIN (vNIN), with optional instant PDF slip generation.

POST /api/nin/verify

Request Parameters

Field	Type	Required	Description
`verification_type`	String	No	`nin` (default), `phone`, `demographic`, or `vnin`
`nin`	String	Conditional	11-digit NIN or 16-char vNIN (Required if verification_type is `nin` or `vnin`)
`phone`	String	Conditional	Nigerian phone number (Required if verification_type is `phone`)
`first_name`	String	Conditional	First name (Required if verification_type is `demographic`)
`last_name`	String	Conditional	Last name (Required if verification_type is `demographic`)
`dob`	String	Conditional	Date of birth in `YYYY-MM-DD` format
`gender`	String	No	`male` or `female`
`slip_type`	String	No	`premium` (default, ₦1000), `standard` (₦700), `regular` (₦500), `vnin` (₦400)
`generate_slip`	Integer	No	`1` to generate downloadable PDF slip

cURL Example

curl -X POST https://asadhub.com.ng/docs/api/nin/verify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verification_type": "nin",
    "nin": "10293847561",
    "slip_type": "premium",
    "generate_slip": 1
  }'

Success Response (HTTP 200)

{
  "status": "success",
  "message": "Verification completed successfully",
  "data": {
    "success": true,
    "reference": "VER8193ABCD1700",
    "amount_charged": 1000,
    "balance": 24000.00,
    "formatted_balance": "₦24,000.00",
    "data": {
      "nin": "10293847561",
      "firstname": "CHUKWUDI",
      "surname": "IBRAHIM",
      "middlename": "ADEBAYO",
      "birthdate": "1992-06-15",
      "telephoneno": "08012345678",
      "gender": "m",
      "residence_address": "Plot 42, Independence Layout, Victoria Island, Lagos",
      "tracking_id": "TRK-A78C43FE",
      "photo": "data:image/png;base64,...",
      "slip_url": "https://dataverify.com.ng/slips/sample_nin_slip.pdf",
      "status": "verified"
    }
  }
}

NIN Record Validation

Perform advanced validations against NIMC records including bank account cross-referencing, telco SIM linkage, no-record resolution, and biometric photo error checks.

POST /api/nin/validate

Request Parameters

Field	Type	Required	Description
`nin`	String	Yes	11-digit NIN Number
`validation_type`	String	No	`record` (default, ₦200), `bank` (₦1500), `sim` (₦1500), `no-record` (₦3000), `photo-error` (₦5000)
`bank_name`	String	Conditional	Bank name (Required for `bank` validation)
`account_number`	String	Conditional	10-digit NUBAN account number (Required for `bank` validation)
`phone_number`	String	Conditional	Phone number (Required for `sim` validation)

cURL Example

curl -X POST https://asadhub.com.ng/docs/api/nin/validate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nin": "10293847561",
    "validation_type": "bank",
    "bank_name": "Access Bank",
    "account_number": "0123456789"
  }'

NIN Data Modification

Submit official NIN modification requests for Date of Birth (₦40,000), Name (₦6,000), Address (₦6,000), Phone (₦6,000), or General Data with tracking reference and document attachments.

POST /api/nin/modify

Request Parameters (Multipart / JSON)

Field	Type	Required	Description
`nin`	String	Yes	11-digit NIN number
`modification_type`	String	Yes	`dob`, `name`, `address`, `phone`, or `general`
`old_value`	String	Yes	Current incorrect value on NIMC record
`new_value`	String	Yes	Requested correct new value
`reason`	String	No	Explanation / reason for modification
`document`	File	No	Supporting certificate, affidavit, or court order (JPG/PNG/PDF)

cURL Example

curl -X POST https://asadhub.com.ng/docs/api/nin/modify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nin": "10293847561",
    "modification_type": "dob",
    "old_value": "1995-04-10",
    "new_value": "1992-06-15",
    "reason": "Birth certificate correction"
  }'

BVN Instant Verification

Instant Bank Verification Number (BVN) lookup returning complete verified customer identity, photo image, enrollment bank, and registered phone details.

POST /api/bvn/verify

Request Parameters

Field	Type	Required	Description
`bvn`	String	Yes	11-digit Bank Verification Number

cURL Example

curl -X POST https://asadhub.com.ng/docs/api/bvn/verify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bvn": "22114477889"
  }'

Success Response (HTTP 200)

{
  "status": "success",
  "message": "Verification completed successfully",
  "data": {
    "success": true,
    "reference": "VER9922ABCD1700",
    "amount_charged": 150,
    "balance": 23850.00,
    "formatted_balance": "₦23,850.00",
    "data": {
      "bvn": "22114477889",
      "first_name": "CHUKWUDI",
      "middle_name": "EMMANUEL",
      "last_name": "IBRAHIM",
      "date_of_birth": "1992-06-15",
      "phone_number1": "08012345678",
      "gender": "Male",
      "enrollment_bank": "FIRST BANK OF NIGERIA",
      "enrollment_branch": "LAGOS MAIN BRANCH",
      "image": "data:image/png;base64,...",
      "status": "verified"
    }
  }
}

BVN Slip Printing

Generate high-resolution printable BVN card and slip PDFs with embedded official verification watermarks.

POST /api/bvn/slip

Request Parameters

Field	Type	Required	Description
`bvn`	String	Yes	11-digit BVN

cURL Example

curl -X POST https://asadhub.com.ng/docs/api/bvn/slip \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bvn": "22114477889"
  }'

BVN Retrieval Service

Retrieve lost or forgotten BVN numbers using registered phone number or customer demographic match.

POST /api/bvn/retrieve

Request Parameters

Field	Type	Required	Description
`phone`	String	Conditional	Registered phone number
`first_name`	String	Conditional	First name
`last_name`	String	Conditional	Surname / Last name
`dob`	String	Conditional	Date of birth (`YYYY-MM-DD`)

cURL Example

curl -X POST https://asadhub.com.ng/docs/api/bvn/retrieve \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "08012345678"
  }'

BVN Modification Request

Submit BVN detail modification requests (Name change, Date of Birth change, Phone update, Gender correction).

POST /api/bvn/modify

Request Parameters

Field	Type	Required	Description
`bvn`	String	Yes	11-digit BVN
`modification_type`	String	Yes	`name`, `dob`, `phone`, or `gender`
`old_value`	String	Yes	Old value on record
`new_value`	String	Yes	Requested new value
`reason`	String	No	Reason for change
`document`	File	No	Supporting document file

IPE Clearance & Birth Attestation

Submit official IPE Clearance requests or National Population Commission (NPC) Birth Attestation applications.

POST /api/ipe/clearance

curl -X POST https://asadhub.com.ng/docs/api/ipe/clearance \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_id": "IPE-948271",
    "category": "General"
  }'

POST /api/birth-attestation

curl -X POST https://asadhub.com.ng/docs/api/birth-attestation \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "CHUKWUDI EMMANUEL IBRAHIM",
    "dob": "1995-08-20",
    "state_of_origin": "Lagos",
    "lga": "Ikeja"
  }'

Verification History

Retrieve paginated audit logs of all past NIN, BVN, and modification requests performed by your account.

GET /api/verification/history?service_type=nin&page=1&limit=20

curl -X GET "https://asadhub.com.ng/docs/api/verification/history?page=1&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Response Formats & Error Codes

All API endpoints return standardized JSON payloads with HTTP response status codes.

Prepaid Electricity Token Success Response (HTTP 200)

{
  "status": "success",
  "message": "Electricity purchase successful",
  "data": {
    "reference": "ELE7492ABCD1700",
    "provider_reference": "ELEC_9F4A12B",
    "category": "electricity",
    "amount": 2000,
    "balance": 23000.50,
    "formatted_balance": "₦23,000.50",
    "token": "4182-9301-2384-5920-1849",
    "units": "29.2 kWh",
    "meter_number": "01429817462",
    "meter_type": "prepaid",
    "disco": "IKEDC"
  }
}

Cable TV Subscription Success Response (HTTP 200)

{
  "status": "success",
  "message": "Cable purchase successful",
  "data": {
    "reference": "CAB8193ABCD1700",
    "provider_reference": "CABLE_3E881B",
    "category": "cable",
    "amount": 4100,
    "balance": 18900.50,
    "formatted_balance": "₦18,900.50",
    "decoder_number": "2019482710",
    "plan_name": "GOtv Max"
  }
}

Error Response Format (HTTP 4xx / 5xx)

{
  "status": "error",
  "message": "Insufficient wallet balance. Please fund your wallet."
}