networkdatasub API

Beta v1.0
BETA This API is in beta. Some endpoints may change before the official release.

Introduction

Welcome to the networkdatasub API documentation. This API allows you to programmatically access our services including airtime purchase, data purchase, and identity verification.

The API is organized around REST principles. All requests should be made over HTTPS, and all response data is returned as JSON.

Base URL: https://www.networkdatasub.com/api

API Overview

The networkdatasub API is organized into the following service groups. All endpoints return JSON responses. Authentication is via Bearer token in the Authorization header unless otherwise noted.

Service Base Path Auth Status
Authentication /api/auth/* Public Available
User /api/user/* Token Available
Wallet /api/wallet/* Token Available
Airtime /api/airtime/* Token Available
Data /api/data/* Token Available
Cable TV /api/cable/* Token Available
Electricity /api/electricity/* Token Available
Recharge Card /api/recharge-card/* Token Available
NIN Verification /api/verification/nin/* Token Available
BVN Verification /api/verification/bvn/* Token Available

Authentication

The networkdatasub API uses token-based authentication. You need to include your API token in the Authorization header of all requests.

Obtaining an API Token

You can generate an API token from your API Tokens page.

Using Your API Token

Include your API token in the Authorization header as follows:

Header Example 
Authorization: Token YOUR_API_TOKEN

Testing Authentication

You can test if your authentication is working correctly by making a request to the user endpoint:

cURL Example 
curl -X GET "https://www.networkdatasub.com/api/user" \
     -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Accept: application/json"

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of an API request.

In general:

Error Response Format

Error responses include a JSON object with the following structure:

Error Response Example 
{
    "success": false,
    "message": "A human-readable error message",
    "errors": {
        "field_name": [
            "Specific error for this field"
        ]
    }
}

Common Error Codes

Status Code Description
400 Bad Request The request was invalid or cannot be otherwise served.
401 Unauthorized Authentication failed or user doesn't have permissions.
404 Not Found The requested resource doesn't exist.
422 Unprocessable Entity The request was well-formed but was unable to be followed due to semantic errors.
429 Too Many Requests Too many requests hit the API too quickly.
500 Server Error Something went wrong on our end.

User

GET Get Current User
GET https://www.networkdatasub.com/api/user

Returns information about the authenticated user.

Response

Response Example 
{
    "success": true,
    "data": {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com",
        "phone": "08012345678",
        "wallet": {
            "balance": 5000.00
        }
    }
}

User Profile

GET Get User Profile
GET https://www.networkdatasub.com/api/user/profile

Returns detailed information about the authenticated user's profile.

Response

Response Example 
{
    "success": true,
    "data": {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com",
        "phone": "08012345678",
        "avatar": "https://example.com/avatars/user1.jpg",
        "address": "123 Main Street, Lagos",
        "gender": "Male",
        "date_of_birth": "1990-01-01",
        "is_verified": true,
        "verification_status": {
            "email": true,
            "phone": true,
            "id": false
        },
        "wallet": {
            "balance": 5000.00,
            "currency": "NGN",
            "last_funded": "2025-04-01T12:30:45.000000Z"
        },
        "joined_at": "2024-10-15T08:45:12.000000Z"
    }
}

Networks

GET Get Airtime Networks
GET https://www.networkdatasub.com/api/airtime/networks

Returns available mobile networks for airtime purchase. Auth: API Token

Response

Response Example 
{
    "success": true,
    "data": [
        {"id": 1, "name": "MTN", "code": "mtn"},
        {"id": 2, "name": "Airtel", "code": "airtel"},
        {"id": 3, "name": "Glo", "code": "glo"},
        {"id": 4, "name": "9Mobile", "code": "9mobile"}
    ]
}
GET Get Data Networks (Public)
GET https://www.networkdatasub.com/api/public/networks

Returns available networks for data services. No auth required.

GET Get Airtime Types / Denominations
GET https://www.networkdatasub.com/api/airtime/types

Returns available airtime types. Auth: API Token

Airtime

GET Get Available Networks
GET https://www.networkdatasub.com/api/airtime/networks

Returns a list of available mobile networks for airtime purchase. Auth: API Token

Response

Response Example 
{
    "success": true,
    "data": [
        {"id": 1, "name": "MTN", "code": "mtn"},
        {"id": 2, "name": "Airtel", "code": "airtel"},
        {"id": 3, "name": "Glo", "code": "glo"},
        {"id": 4, "name": "9Mobile", "code": "9mobile"}
    ]
}
GET Get Airtime Types
GET https://www.networkdatasub.com/api/airtime/types

Returns networks with their supported airtime types (VTU, Awuf4u, Share & Sell). Auth: API Token

POST Purchase Airtime
POST https://www.networkdatasub.com/api/airtime/purchase

Purchase airtime for a phone number. Auth: API Token

Request Parameters

Parameter Type Description
network Required integer Network ID (1=MTN, 2=Airtel, 3=Glo, 4=9Mobile)
phone Required string Phone number to recharge (11 digits)
amount Required number Amount to recharge (min: 50, max: 50000)
airtime_type Optional string vtu (default), awuf4u, share_and_sell
Request Example
Response Example
Error Example
cURL Example 
curl -X POST "https://www.networkdatasub.com/api/airtime/purchase" \
     -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
         "network": 1,
         "phone": "08012345678",
         "amount": 100
     }'
Success Response 
{
    "success": true,
    "message": "Airtime purchased successfully",
    "data": {
        "transaction": {
            "id": 123,
            "reference": "AIRXYZ12345",
            "amount": 100,
            "status": "completed",
            "created_at": "2025-04-15T10:30:00.000000Z"
        },
        "new_balance": 4900.00
    }
}
Error Response 
{
    "success": false,
    "message": "Failed to purchase airtime: Insufficient wallet balance",
    "data": {
        "required_amount": 100,
        "current_balance": 50
    }
}

Data

GET Get Available Networks for Data
GET https://www.networkdatasub.com/api/data/networks

Returns a list of available networks that support data services.

Response

Response Example 
{
    "success": true,
    "message": "Data networks retrieved successfully",
    "data": [
        {
            "id": 1,
            "name": "MTN",
            "code": "mtn",
            "logo": "https://example.com/logos/mtn.png",
            "status": "active",
            "data_types": ["SME", "Direct", "Corporate"]
        },
        {
            "id": 2,
            "name": "Airtel",
            "code": "airtel",
            "logo": "https://example.com/logos/airtel.png",
            "status": "active",
            "data_types": ["Direct", "Corporate"]
        },
        {
            "id": 3,
            "name": "Glo",
            "code": "glo",
            "logo": "https://example.com/logos/glo.png",
            "status": "active",
            "data_types": ["Direct"]
        },
        {
            "id": 4,
            "name": "9Mobile",
            "code": "9mobile",
            "logo": "https://example.com/logos/9mobile.png",
            "status": "active",
            "data_types": ["Direct", "SME"]
        }
    ]
}
GET Get Data Plans
GET https://www.networkdatasub.com/api/data-plans

Returns a list of available data plans for a specific network.

Query Parameters

Parameter Type Description
network Required string Network code (e.g., mtn, airtel, glo, 9mobile)
type Optional string Data plan type (e.g., SME, Corporate, Direct)

Response

Response Example 
{
    "success": true,
    "message": "Data plans retrieved successfully",
    "data": [
        {
            "id": 1,
            "network_id": 1,
            "name": "1GB (30 Days)",
            "code": "1GB",
            "amount": 300,
            "validity": "30 days",
            "type": "SME",
            "description": "1GB data valid for 30 days"
        },
        {
            "id": 2,
            "network_id": 1,
            "name": "2GB (30 Days)",
            "code": "2GB",
            "amount": 500,
            "validity": "30 days",
            "type": "SME",
            "description": "2GB data valid for 30 days"
        },
        {
            "id": 3,
            "network_id": 1,
            "name": "5GB (30 Days)",
            "code": "5GB",
            "amount": 1000,
            "validity": "30 days",
            "type": "SME",
            "description": "5GB data valid for 30 days"
        }
    ]
}
POST Purchase Data
POST https://www.networkdatasub.com/api/data/purchase

Purchase a data plan for a phone number. Integrated with NetworkDataSub API for instant data delivery across all Nigerian networks.

Request Parameters

Parameter Type Description
data_plan_id Required integer Data plan ID from database (can be api_plan_id or plan_id)
phone_number Required string Phone number (10-15 digits, supports +, -, spaces)

Request Example

cURL Example 
# Complete cURL Example - Data Purchase
curl -X POST "https://www.networkdatasub.com/api/data/purchase" \
     -H "Authorization: Token your_actual_api_token_here" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "User-Agent: YourApp/1.0" \
     -v \
     --data-raw '{
         "data_plan_id": 7,
         "phone_number": "08012345678"
     }'

# Alternative plan examples:
# {"data_plan_id": 173, "phone_number": "07012345678"}
# {"data_plan_id": 174, "phone_number": "08512345678"}  
# {"data_plan_id": 175, "phone_number": "09012345678"}

# PHP cURL Example:
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://www.networkdatasub.com/api/data/purchase',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode([
        'data_plan_id' => 7,
        'phone_number' => '08012345678'
    ]),
    CURLOPT_HTTPHEADER => array(
        'Authorization: Token your_actual_api_token_here',
        'Accept: application/json',
        'Content-Type: application/json'
    ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>

NetworkDataSub Integration Flow

Behind the Scenes:
  1. Your API receives: {"data_plan_id": 7, "phone_number": "08012345678"}
  2. Phone validated and cleaned: "08012345678"
  3. Sent to NetworkDataSub: {"network": "mtn", "data_plan_id": 7, "phone_number": "08012345678"}
  4. NetworkDataSub processes payment & delivers data
  5. Response formatted for your API clients

Response

Response Example 
{
    "success": true,
    "message": "Data purchased successfully",
    "data": {
        "transaction_id": 124,
        "reference": "DATAXYZ12345",
        "amount": 500,
        "status": "completed",
        "new_balance": 4400.00,
        "phone_number": "080****78",
        "network": "MTN",
        "plan_id": 7
    }
}

Cable TV

GET Get Cable TV Providers
GET https://www.networkdatasub.com/api/cable/providers

Returns a list of available cable TV providers (DSTV, GOTV, Startimes, etc.).

Response

Response Example 
{
    "success": true,
    "message": "Cable TV providers retrieved successfully",
    "data": [
        {
            "id": 1,
            "name": "DSTV",
            "code": "dstv",
            "logo": "https://example.com/logos/dstv.png",
            "status": "active"
        },
        {
            "id": 2,
            "name": "GOTV",
            "code": "gotv",
            "logo": "https://example.com/logos/gotv.png",
            "status": "active"
        },
        {
            "id": 3,
            "name": "Startimes",
            "code": "startimes",
            "logo": "https://example.com/logos/startimes.png",
            "status": "active"
        }
    ]
}
POST Subscribe to Cable TV
POST https://www.networkdatasub.com/api/cable/subscribe

Subscribe to a cable TV package for a smartcard number.

Request Parameters

Parameter Type Description
provider Required string Cable provider code (e.g., dstv, gotv, startimes)
smartcard_number Required string Smartcard number
package_code Required string Package code
amount Required number Subscription amount

Response

Response Example 
{
    "success": true,
    "message": "Cable TV subscription successful",
    "data": {
        "transaction_id": 456,
        "reference": "CABLE123456",
        "provider": "DSTV",
        "smartcard_number": "123****890",
        "package": "Compact Plus",
        "amount": 15000,
        "status": "completed",
        "new_balance": 25000.00
    }
}

Electricity

GET Get Electricity Providers
GET https://www.networkdatasub.com/api/electricity/providers

Returns a list of available electricity distribution companies.

Response

Response Example 
{
    "success": true,
    "message": "Electricity providers retrieved successfully",
    "data": [
        {
            "id": 1,
            "name": "Ikeja Electric (IKEDC)",
            "code": "ikeja-electric",
            "status": "active"
        },
        {
            "id": 2,
            "name": "Eko Electric (EKEDC)",
            "code": "eko-electric",
            "status": "active"
        },
        {
            "id": 3,
            "name": "Abuja Electric (AEDC)",
            "code": "abuja-electric",
            "status": "active"
        },
        {
            "id": 4,
            "name": "Port Harcourt Electric",
            "code": "portharcourt-electric",
            "status": "active"
        }
    ]
}
POST Purchase Electricity
POST https://www.networkdatasub.com/api/electricity/purchase

Purchase electricity units/tokens for a meter number.

Request Parameters

Parameter Type Description
provider Required string Electricity provider code
meter_number Required string Meter number
meter_type Required string Meter type (prepaid or postpaid)
amount Required number Amount to purchase (minimum 500)
phone Required string Phone number

Response

Response Example 
{
    "success": true,
    "message": "Electricity purchased successfully",
    "data": {
        "transaction_id": 789,
        "reference": "ELEC789012",
        "provider": "Ikeja Electric",
        "meter_number": "123****890",
        "meter_type": "prepaid",
        "amount": 5000,
        "units": "45.67 kWh",
        "token": "1234-5678-9012-3456-7890",
        "status": "completed",
        "new_balance": 15000.00
    }
}

Recharge Card

GET Get Recharge Card Networks
GET https://www.networkdatasub.com/api/recharge-card/networks

Returns a list of available networks for recharge card (data PIN) purchase.

Response

Response Example 
{
    "success": true,
    "message": "Networks retrieved successfully",
    "data": [
        {
            "id": 1,
            "name": "MTN",
            "code": "mtn",
            "status": "active",
            "plans_count": 15
        },
        {
            "id": 2,
            "name": "Airtel",
            "code": "airtel",
            "status": "active",
            "plans_count": 12
        },
        {
            "id": 3,
            "name": "Glo",
            "code": "glo",
            "status": "active",
            "plans_count": 10
        },
        {
            "id": 4,
            "name": "9Mobile",
            "code": "9mobile",
            "status": "active",
            "plans_count": 8
        }
    ]
}
POST Purchase Recharge Card (Data PIN)
POST https://www.networkdatasub.com/api/recharge-card/purchase

Purchase data recharge card PINs. This generates printable PINs that can be used to load data.

Request Parameters

Parameter Type Description
network_id Required integer Network ID (1=MTN, 2=Airtel, 3=Glo, 4=9Mobile)
plan_id Required integer Data plan ID
quantity Required integer Number of PINs to generate (1-50)

Response

Response Example 
{
    "success": true,
    "message": "Recharge cards generated successfully",
    "data": {
        "transaction_id": 234,
        "batch_id": "BATCH789012",
        "network": "MTN",
        "plan_name": "1GB (30 Days)",
        "quantity": 5,
        "total_amount": 1500,
        "status": "completed",
        "new_balance": 8500.00,
        "cards": [
            {
                "id": 1,
                "pin": "1234-5678-9012",
                "serial": "9876543210123",
                "status": "unused",
                "expires_at": "2026-03-16"
            },
            {
                "id": 2,
                "pin": "2345-6789-0123",
                "serial": "9876543210124",
                "status": "unused",
                "expires_at": "2026-03-16"
            }
        ],
        "print_url": "https://www.networkdatasub.com/api/recharge-card/print/BATCH789012"
    }
}
GET Get Recharge Card History
GET https://www.networkdatasub.com/api/recharge-card/history

Returns the history of purchased recharge cards with pagination.

Query Parameters

Parameter Type Description
page Optional integer Page number (default: 1)
per_page Optional integer Items per page (default: 20, max: 100)
status Optional string Filter by status (unused, used, expired)

Response

Response Example 
{
    "success": true,
    "message": "History retrieved successfully",
    "data": [
        {
            "id": 234,
            "batch_id": "BATCH789012",
            "network": "MTN",
            "plan_name": "1GB (30 Days)",
            "quantity": 5,
            "total_amount": 1500,
            "status": "completed",
            "created_at": "2026-02-15T10:30:00Z",
            "cards_unused": 3,
            "cards_used": 2
        }
    ],
    "pagination": {
        "current_page": 1,
        "total_pages": 5,
        "per_page": 20,
        "total_items": 95
    }
}

Wallet

All wallet endpoints require API Token authentication. Include the token in the Authorization: Token YOUR_API_TOKEN header.

Base URL: https://www.networkdatasub.com/api

GET Get Wallet
GET https://www.networkdatasub.com/api/wallet

Returns the authenticated user's wallet information including balance. Auth: API Token

GET Get Wallet Balance
GET https://www.networkdatasub.com/api/user/balance

Returns user's wallet balance. Auth: API Token

GET Get Wallet Transactions
GET https://www.networkdatasub.com/api/wallet/transactions

Returns wallet transaction history. Auth: API Token

POST Fund Wallet
POST https://www.networkdatasub.com/api/wallet/fund

Initiates a funding request. Auth: API Token

Request Parameters

Parameter Type Description
amount Required number Amount to fund (min: 100, max: 500000)
payment_method Required string card, bank_transfer, virtual_account
POST Verify Wallet Funding
POST https://www.networkdatasub.com/api/wallet/verify-funding

Verify a pending wallet funding transaction. Auth: API Token

Request Parameters

Parameter Type Description
reference Required string Transaction reference from fund endpoint
GET Get Virtual Accounts
GET https://www.networkdatasub.com/api/wallet/virtual-accounts

Returns all virtual accounts (PalmPay, 9PSB, Safehaven). Auth: API Token

Response

Response Example 
{
    "success": true,
    "data": {
        "accounts": [
            {"account_number": "1234567890", "bank_name": "PalmPay", "is_primary": true},
            {"account_number": "0987654321", "bank_name": "9PSB", "is_primary": false}
        ]
    }
}
POST Create Virtual Accounts
POST https://www.networkdatasub.com/api/wallet/virtual-accounts/create

Generates virtual accounts across all banks (PalmPay, 9PSB, Safehaven). Skips banks that already exist. Auth: API Token

Request Example 
curl -X POST "https://www.networkdatasub.com/api/wallet/fund" \
     -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
         "amount": 5000,
         "payment_method": "card",
         "redirect_url": "https://yourdomain.com/payment-callback"
     }'
Response Example 
{
    "success": true,
    "message": "Funding request initiated successfully",
    "data": {
        "reference": "FND-XYZ12345",
        "amount": "5000.00",
        "status": "pending",
        "payment_url": "https://checkout.paymentgateway.com/pay/xyz12345",
        "expires_at": "2025-05-20T15:30:45.000000Z"
    }
}

Transactions

GET Get Transaction History
GET https://www.networkdatasub.com/api/user/transactions

Returns a list of transactions for the authenticated user. Auth: API Token

Query Parameters

Parameter Type Description
page Optional integer Page number for pagination (default: 1)
per_page Optional integer Number of records per page (default: 15, max: 50)
type Optional string Filter by transaction type (credit, debit)
start_date Optional string (YYYY-MM-DD) Filter by start date
end_date Optional string (YYYY-MM-DD) Filter by end date
status Optional string Filter by status (pending, completed, failed)

Response

Response Example 
{
    "success": true,
    "message": "Transactions retrieved successfully",
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": 456,
                "user_id": 1,
                "type": "debit",
                "amount": "300.00",
                "reference": "DATA-XYZ123",
                "description": "MTN Data Purchase - 1GB",
                "status": "completed",
                "meta": {
                    "phone": "08012345678",
                    "network": "mtn",
                    "plan": "1GB",
                    "service_type": "data"
                },
                "created_at": "2025-05-15T08:30:45.000000Z"
            },
            {
                "id": 455,
                "user_id": 1,
                "type": "credit",
                "amount": "2000.00",
                "reference": "FND-ABC789",
                "description": "Wallet funding via Bank Transfer",
                "status": "completed",
                "meta": {
                    "payment_method": "bank_transfer",
                    "bank_name": "First Bank",
                    "payment_reference": "TRF12345"
                },
                "created_at": "2025-05-10T14:22:18.000000Z"
            }
        ],
        "first_page_url": "https://www.networkdatasub.com/api/transactions?page=1",
        "from": 1,
        "last_page": 5,
        "last_page_url": "https://www.networkdatasub.com/api/transactions?page=5",
        "next_page_url": "https://www.networkdatasub.com/api/transactions?page=2",
        "path": "https://www.networkdatasub.com/api/transactions",
        "per_page": 15,
        "prev_page_url": null,
        "to": 15,
        "total": 75
    }
}
GET Get Transaction Details
GET https://www.networkdatasub.com/api/user/transactions/{reference}

Returns detailed information about a specific transaction. Auth: API Token

Path Parameters

Parameter Type Description
reference Required string Transaction reference

Response

Response Example 
{
    "success": true,
    "message": "Transaction details retrieved successfully",
    "data": {
        "id": 456,
        "user_id": 1,
        "type": "debit",
        "amount": "300.00",
        "reference": "DATA-XYZ123",
        "description": "MTN Data Purchase - 1GB",
        "status": "completed",
        "balance_before": "5300.00",
        "balance_after": "5000.00",
        "meta": {
            "phone": "08012345678",
            "network": "mtn",
            "plan": "1GB",
            "service_type": "data",
            "validity": "30 days",
            "provider_reference": "PRV-12345",
            "provider_response": {
                "code": 200,
                "message": "Data purchase successful",
                "bundle_remaining": "1024 MB"
            }
        },
        "created_at": "2025-05-15T08:30:45.000000Z",
        "updated_at": "2025-05-15T08:30:50.000000Z"
    }
}

Verification

All verification endpoints require API Token authentication. Include the token in the Authorization: Token YOUR_API_TOKEN header.

Base URL: https://www.networkdatasub.com/api

PDF Support

All verification endpoints now return PDF documents! Every successful NIN and BVN verification includes the following PDF-related fields in the response:

Usage: Decode the pdf_base64 string to get the raw PDF file bytes. The PDF can be saved to disk or displayed directly to the user.

GET Get NIN Verification Pricing
GET https://www.networkdatasub.com/api/verification/nin/pricing

Returns the pricing for different types of NIN verification cards.

Response

Response Example 
{
    "success": true,
    "message": "NIN verification pricing retrieved successfully",
    "data": [
        {
            "id": 1,
            "card_type": "standard",
            "price": 100,
            "is_active": true,
            "description": "Standard verification"
        },
        {
            "id": 2,
            "card_type": "regular",
            "price": 150,
            "is_active": true,
            "description": "Regular verification"
        },
        {
            "id": 3,
            "card_type": "premium",
            "price": 200,
            "is_active": true,
            "description": "Premium verification with enhanced features"
        },
        {
            "id": 4,
            "card_type": "slip",
            "price": 150,
            "is_active": true,
            "description": "NIN Slip PDF Download"
        }
    ]
}
POST Verify NIN
POST https://www.networkdatasub.com/api/verification/nin

Verify a National Identification Number (NIN).

Important Note: The system will always charge users for verifications, even when the NIN has been previously verified. For previously verified NINs, the system reuses existing data rather than making a new API call, optimizing costs while maintaining service quality.

Request Parameters

Parameter Type Description
nin required string The 11-digit NIN to verify
card_type required string Type of verification card (standard, regular, premium)
force_new optional boolean Force a new verification even if one already exists (default is false)
use_real_api optional boolean Force using the real API instead of mock data (default is false)
Request Example
Response Example
Error Example
Request Example 
curl -X POST "https://www.networkdatasub.com/api/verification/nin" \
     -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
         "nin": "12345678901",
         "card_type": "standard",
         "force_new": false
     }'
Response Example 
{
    "success": true,
    "message": "NIN verification completed successfully",
    "data": {
        "verification_id": 12345,
        "transaction_id": "NIN-ABCDEF12345",
        "reference": "NIN-ABCDEF12345",
        "amount": 100,
        "details": {
            "firstName": "John",
            "middleName": "Doe",
            "lastName": "Smith",
            "dateOfBirth": "01 Jan 1990",
            "gender": "Male",
            "issueDate": "18 May 2025",
            "photo": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=",
            "address": "123 Main Street",
            "state": "Lagos",
            "lga": "Ikeja",
            "town": "Ikeja",
            "mobile": "08012345678",
            "nin": "12345678901",
            "signature": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
        },
        "pdf_base64": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmo8PAovVHlwZSAvUGFnZXMKL0tpZHMgWzMgMCBSXQovQ291bnQgMQo+PgplbmRvYmoKMyAwIG9iago8PAovVHlwZSAvUGFnZQovUGFyZW50IDIgMCBSCj4+CmVuZG9iagp4cmVmCjAgNAowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMTAgMDAwMDAgbiAKMDAwMDAwMDA1MyAwMDAwMCBuIAowMDAwMDAwMTAyIDAwMDAwIG4gCnRyYWlsZXIKPDwKL1NpemUgNAovUm9vdCAxIDAgUgo+PgpzdGFydHhyZWYKMTQ5CiUlRU9G",
        "has_pdf": true,
        "wallet_balance": "5000.00"
    }
}
Error Example 
{
    "success": false,
    "message": "Insufficient wallet balance. Please fund your wallet to continue.",
    "data": {
        "required_amount": 100,
        "current_balance": 50
    }
}
POST Verify NIN (Card Type Specific)
POST https://www.networkdatasub.com/api/verification/nin/standard
POST https://www.networkdatasub.com/api/verification/nin/regular
POST https://www.networkdatasub.com/api/verification/nin/premium

Verify a National Identification Number (NIN) using card type specific endpoints. These endpoints automatically use the specified card type without requiring the card_type parameter.

Request Parameters

Parameter Type Description
nin required string The 11-digit NIN to verify
force_new optional boolean Force a new verification even if one already exists (default is false)
Request Example
Response Example
Standard Request Example 
curl -X POST "https://www.networkdatasub.com/api/verification/nin/standard" \
     -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
         "nin": "12345678901"
     }'
Response Example 
{
    "success": true,
    "message": "NIN verification completed successfully",
    "data": {
        "verification_id": 12345,
        "transaction_id": "NIN-ABCDEF12345",
        "reference": "NIN-ABCDEF12345",
        "amount": 100,
        "card_type": "standard",
        "details": {
            "firstName": "John",
            "middleName": "Doe",
            "lastName": "Smith",
            "dateOfBirth": "01 Jan 1990",
            "gender": "Male",
            "nin": "12345678901"
        },
        "pdf_base64": "JVBERi0xLjQKJeLjz9MK...",
        "has_pdf": true,
        "wallet_balance": "5000.00"
    }
}
POST Get NIN Slip (PDF)
POST https://www.networkdatasub.com/api/verification/nin/slip

Get a NIN verification slip as a PDF document. This endpoint returns only the PDF document for display or download purposes.

Request Parameters

Parameter Type Description
nin required string The 11-digit NIN to get slip for
Request Example
Response Example
Request Example 
curl -X POST "https://www.networkdatasub.com/api/verification/nin/slip" \
     -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
         "nin": "12345678901"
     }'
Response Example 
{
    "success": true,
    "message": "NIN slip retrieved successfully",
    "data": {
        "verification_id": 12345,
        "transaction_id": "NIN-SLIP-ABCDEF12345",
        "reference": "NIN-SLIP-ABCDEF12345",
        "amount": 150,
        "pdf_base64": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmo8PAovVHlwZSAvUGFnZXMKL0tpZHMgWzMgMCBSXQovQ291bnQgMQo+PgplbmRvYmoKMyAwIG9iago8PAovVHlwZSAvUGFnZQovUGFyZW50IDIgMCBSCj4+CmVuZG9iagp4cmVmCjAgNAowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMTAgMDAwMDAgbiAKMDAwMDAwMDA1MyAwMDAwMCBuIAowMDAwMDAwMTAyIDAwMDAwIG4gCnRyYWlsZXIKPDwKL1NpemUgNAovUm9vdCAxIDAgUgo+PgpzdGFydHhyZWYKMTQ5CiUlRU9G",
        "has_pdf": true,
        "wallet_balance": "4850.00"
    }
}
POST Search NIN by Phone Number
POST https://www.networkdatasub.com/api/verification/nin/phone-search

Search for a NIN using a phone number. This endpoint retrieves NIN information associated with the provided phone number.

Request Parameters

Parameter Type Description
phone required string The phone number to search (11 digits, e.g., 08012345678)
card_type required string Type of verification card (standard, regular, premium)
Request Example
Response Example
Request Example 
curl -X POST "https://www.networkdatasub.com/api/verification/nin/phone-search" \
     -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
         "phone": "08012345678",
         "card_type": "standard"
     }'
Response Example 
{
    "success": true,
    "message": "Phone number verification completed successfully",
    "data": {
        "verification_id": 12345,
        "transaction_id": "NIN-PHONE-ABCDEF12345",
        "reference": "NIN-PHONE-ABCDEF12345",
        "amount": 100,
        "details": {
            "firstName": "John",
            "middleName": "Doe",
            "lastName": "Smith",
            "dateOfBirth": "01 Jan 1990",
            "gender": "Male",
            "phone": "08012345678",
            "nin": "12345678901"
        },
        "pdf_base64": "JVBERi0xLjQKJeLjz9MK...",
        "has_pdf": true,
        "wallet_balance": "4900.00"
    }
}
GET Get BVN Verification Pricing
GET https://www.networkdatasub.com/api/verification/bvn/pricing

Returns the pricing for different types of BVN verification cards.

Response

Response Example 
{
    "success": true,
    "message": "BVN verification pricing retrieved successfully",
    "data": [
        {
            "id": 1,
            "card_type": "standard",
            "price": 300,
            "is_active": true,
            "description": "Standard BVN verification"
        },
        {
            "id": 2,
            "card_type": "premium",
            "price": 500,
            "is_active": true,
            "description": "Premium BVN verification with enhanced data"
        }
    ]
}
POST Verify BVN
POST https://www.networkdatasub.com/api/verification/bvn

Verify a Bank Verification Number (BVN).

Important Note: The system will always charge users for verifications, even when the BVN has been previously verified. For previously verified BVNs, the system reuses existing data rather than making a new API call, optimizing costs while maintaining service quality.

Request Parameters

Parameter Type Description
bvn required string The 11-digit BVN to verify
card_type required string Type of verification card (standard, premium)
provider optional string The verification provider, either "idpass" or "mobilsix" (default is "idpass")
force_new optional boolean Force a new verification even if one already exists (default is false)
use_real_api optional boolean Force using the real API instead of mock data (default is false)
Request Example
Response Example
Error Example
Request Example 
curl -X POST "https://www.networkdatasub.com/api/verification/bvn" \
     -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
         "bvn": "12345678901",
         "card_type": "standard",
         "provider": "idpass",
         "force_new": false
     }'
Response Example 
{
    "success": true,
    "message": "BVN verification completed successfully",
    "data": {
        "verification_id": 123,
        "transaction_id": "MOCK-ABCDEF123456",
        "reference": "BVN-ABC123DEF456",
        "amount": 300,
        "provider": "dataverify",
        "details": {
            "bvn": "12345678901",
            "firstName": "John",
            "lastName": "Doe",
            "middleName": "Smith",
            "dateOfBirth": "1990-01-01",
            "phoneNumber": "08012345678",
            "gender": "Male",
            "email": "john.doe@example.com",
            "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
        },
        "pdf_base64": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmo8PAovVHlwZSAvUGFnZXMKL0tpZHMgWzMgMCBSXQovQ291bnQgMQo+PgplbmRvYmoKMyAwIG9iago8PAovVHlwZSAvUGFnZQovUGFyZW50IDIgMCBSCj4+CmVuZG9iagp4cmVmCjAgNAowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMTAgMDAwMDAgbiAKMDAwMDAwMDA1MyAwMDAwMCBuIAowMDAwMDAwMTAyIDAwMDAwIG4gCnRyYWlsZXIKPDwKL1NpemUgNAovUm9vdCAxIDAgUgo+PgpzdGFydHhyZWYKMTQ5CiUlRU9G",
        "has_pdf": true,
        "wallet_balance": "9700.00"
    }
}
Error Example 
{
    "success": false,
    "message": "Insufficient wallet balance. Please fund your wallet to continue.",
    "data": {
        "required_amount": 300,
        "current_balance": 100
    }
}
POST Verify BVN (Card Type Specific)
POST https://www.networkdatasub.com/api/verification/bvn/standard
POST https://www.networkdatasub.com/api/verification/bvn/premium

Verify a Bank Verification Number (BVN) using card type specific endpoints. These endpoints automatically use the specified card type without requiring the card_type parameter.

Request Parameters

Parameter Type Description
bvn required string The 11-digit BVN to verify
force_new optional boolean Force a new verification even if one already exists (default is false)
Request Example
Response Example
Standard Request Example 
curl -X POST "https://www.networkdatasub.com/api/verification/bvn/standard" \
     -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
         "bvn": "22410993073"
     }'
Response Example 
{
    "success": true,
    "message": "BVN verification completed successfully",
    "data": {
        "verification_id": 123,
        "transaction_id": "BVN-ABCDEF123456",
        "reference": "BVN-ABC123DEF456",
        "amount": 300,
        "card_type": "standard",
        "provider": "dataverify",
        "details": {
            "bvn": "22410993073",
            "firstName": "John",
            "lastName": "Doe",
            "middleName": "Smith",
            "dateOfBirth": "1990-01-01",
            "phoneNumber": "08012345678",
            "gender": "Male",
            "email": "john.doe@example.com",
            "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
        },
        "pdf_base64": "JVBERi0xLjQKJeLjz9MK...",
        "has_pdf": true,
        "wallet_balance": "9700.00"
    }
}
GET Get Verification History
GET https://www.networkdatasub.com/api/verification/nin/history
GET https://www.networkdatasub.com/api/verification/bvn/history

Retrieve the history of all verifications for the authenticated user.

Response Example

NIN History Response 
{
    "success": true,
    "message": "NIN verifications retrieved successfully",
    "data": [
        {
            "id": 12345,
            "user_id": 1,
            "nin_number": "12345678901",
            "transaction_id": "TX-ABCDEF12345",
            "status": "verified",
            "card_type": "standard",
            "price": 100,
            "expires_at": "2026-05-18T12:00:00.000000Z",
            "created_at": "2025-05-18T12:00:00.000000Z",
            "updated_at": "2025-05-18T12:00:00.000000Z"
        }
    ]
}
GET Get Specific Verification Details
GET https://www.networkdatasub.com/api/verification/nin/{id}
GET https://www.networkdatasub.com/api/verification/bvn/{id}

Retrieve detailed information about a specific verification.

Response Example

NIN Details Response 
{
    "success": true,
    "message": "NIN verification retrieved successfully",
    "data": {
        "verification": {
            "id": 12345,
            "user_id": 1,
            "nin_number": "12345678901",
            "transaction_id": "TX-ABCDEF12345",
            "status": "verified",
            "card_type": "standard",
            "price": 100,
            "expires_at": "2026-05-18T12:00:00.000000Z",
            "created_at": "2025-05-18T12:00:00.000000Z",
            "updated_at": "2025-05-18T12:00:00.000000Z"
        },
        "details": {
            "firstName": "John",
            "middleName": "Doe",
            "lastName": "Smith",
            "dateOfBirth": "01 Jan 1990",
            "gender": "Male",
            "issueDate": "18 May 2025",
            "photo": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=",
            "address": "123 Main Street",
            "state": "Lagos",
            "lga": "Ikeja",
            "town": "Ikeja",
            "mobile": "08012345678",
            "nin": "12345678901",
            "signature": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
        }
    }
}