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://networkdatasub.com/api

API Status Overview

The following table provides the current status of our API endpoints. This information is updated as of June 3, 2025.

Endpoint Status Notes
/api/mobile/networks Partial Returns 4 networks, but needs auth fix
/api/user/profile Not Available View not found error - Fix in progress
/api/networks Not Available Route not found - Implementation in progress
/api/data-plans Not Available Authorization required - Implementation in progress
/api/wallet/balance Not Available Route not found - Implementation in progress
/api/data/purchase Partial Error handling works - Implementation in progress
/api/transactions Not Available Route not found - Implementation in progress
/api/user Available Fully functional
/api/verification Available NIN and BVN verification working
/api/airtime Available Fully functional
Note: Our team is actively working on implementing the missing endpoints. This documentation provides information about both available and planned API endpoints. Endpoints marked as "Not Available" or "Partial" are expected to be fully functional by July 2025.

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://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:

  • 2xx status codes indicate success
  • 4xx status codes indicate an error due to the information provided (e.g., missing required parameters)
  • 5xx status codes indicate an error with our servers

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://networkdatasub.com/api/user

Returns information about the authenticated user.

Response

Response Example 
{
    "success": true,
    "data": {
        "id": 1,
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "08012345678",
        "wallet": {
            "balance": 5000.00
        }
    }
}

User Profile

GET Get User Profile
GET https://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": "[email protected]",
        "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 Mobile Networks
GET https://networkdatasub.com/api/mobile/networks

Returns a list of available mobile networks for data and airtime services.

Response

Response Example 
{
    "success": true,
    "message": "Mobile networks retrieved successfully",
    "data": [
        {
            "id": 1,
            "name": "MTN",
            "code": "mtn",
            "logo": "https://example.com/logos/mtn.png",
            "status": "active"
        },
        {
            "id": 2,
            "name": "Airtel",
            "code": "airtel",
            "logo": "https://example.com/logos/airtel.png",
            "status": "active"
        },
        {
            "id": 3,
            "name": "Glo",
            "code": "glo",
            "logo": "https://example.com/logos/glo.png",
            "status": "active"
        },
        {
            "id": 4,
            "name": "9Mobile",
            "code": "9mobile",
            "logo": "https://example.com/logos/9mobile.png",
            "status": "active"
        }
    ]
}
GET Get All Network Providers
GET https://networkdatasub.com/api/networks

Returns a comprehensive list of all network providers including details for API integrations.

Response

Response Example 
{
    "success": true,
    "message": "Networks retrieved successfully",
    "data": [
        {
            "id": 1,
            "name": "MTN",
            "code": "mtn",
            "logo": "https://example.com/logos/mtn.png",
            "status": "active",
            "provider_codes": {
                "wazodata": "mtn-ng",
                "mobilesix": "MTN",
                "telitab": "MTN"
            },
            "data_types": ["SME", "Direct", "Corporate"],
            "supports_airtime": true,
            "supports_data": true,
            "created_at": "2023-01-15T00:00:00.000000Z",
            "updated_at": "2025-04-10T08:30:00.000000Z"
        },
        {
            "id": 2,
            "name": "Airtel",
            "code": "airtel",
            "logo": "https://example.com/logos/airtel.png",
            "status": "active",
            "provider_codes": {
                "wazodata": "airtel-ng",
                "mobilesix": "AIRTEL",
                "telitab": "AIRTEL"
            },
            "data_types": ["Direct", "Corporate"],
            "supports_airtime": true,
            "supports_data": true,
            "created_at": "2023-01-15T00:00:00.000000Z",
            "updated_at": "2025-04-10T08:30:00.000000Z"
        }
    ]
}

Airtime

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

Returns a list of available networks for airtime purchase.

Response

Response Example 
{
    "success": true,
    "message": "Airtime types retrieved successfully",
    "data": [
        {
            "id": 1,
            "name": "MTN",
            "code": "mtn",
            "logo": "https://example.com/logos/mtn.png",
            "status": "active"
        },
        {
            "id": 2,
            "name": "Airtel",
            "code": "airtel",
            "logo": "https://example.com/logos/airtel.png",
            "status": "active"
        },
        {
            "id": 3,
            "name": "Glo",
            "code": "glo",
            "logo": "https://example.com/logos/glo.png",
            "status": "active"
        },
        {
            "id": 4,
            "name": "9Mobile",
            "code": "9mobile",
            "logo": "https://example.com/logos/9mobile.png",
            "status": "active"
        }
    ]
}
POST Purchase Airtime
POST https://networkdatasub.com/api/airtime/purchase

Purchase airtime for a phone number.

Request Parameters

Parameter Type Description
network Required string Network code (e.g., mtn, airtel, glo, 9mobile)
phone Required string Phone number to recharge
amount Required number Amount to recharge (min: 50, max: 50000)
Request Example
Response Example
Error Example
cURL Example 
curl -X POST "https://networkdatasub.com/api/airtime/purchase" \
     -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
         "network": "mtn",
         "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://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://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://networkdatasub.com/api/data/purchase

Purchase a data plan for a phone number.

Request Parameters

Parameter Type Description
network Required string Network code (e.g., mtn, airtel, glo, 9mobile)
plan_id Required integer ID of the data plan
phone Required string Phone number to receive the data

Response

Response Example 
{
    "success": true,
    "message": "Data purchased successfully",
    "data": {
        "transaction": {
            "id": 124,
            "reference": "DATAXYZ12345",
            "amount": 500,
            "status": "completed",
            "created_at": "2025-04-15T11:30:00.000000Z"
        },
        "new_balance": 4400.00
    }
}

Wallet

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

Returns the current balance of the authenticated user's wallet.

Response

Response Example 
{
    "success": true,
    "message": "Wallet balance retrieved successfully",
    "data": {
        "wallet_id": 123,
        "user_id": 1,
        "balance": "5000.00",
        "currency": "NGN",
        "last_funded": "2025-04-01T12:30:45.000000Z",
        "status": "active"
    }
}
GET Get Wallet Summary
GET https://networkdatasub.com/api/wallet/summary

Returns a summary of the authenticated user's wallet, including recent transactions.

Response

Response Example 
{
    "success": true,
    "message": "Wallet summary retrieved successfully",
    "data": {
        "wallet": {
            "id": 123,
            "balance": "5000.00",
            "currency": "NGN",
            "status": "active"
        },
        "stats": {
            "total_inflow": "15000.00",
            "total_outflow": "10000.00",
            "transactions_count": 25,
            "last_transaction_date": "2025-05-15T08:30:45.000000Z"
        },
        "recent_transactions": [
            {
                "id": 456,
                "type": "debit",
                "amount": "300.00",
                "reference": "DATA-XYZ123",
                "description": "MTN Data Purchase - 1GB",
                "status": "completed",
                "created_at": "2025-05-15T08:30:45.000000Z"
            },
            {
                "id": 455,
                "type": "credit",
                "amount": "2000.00",
                "reference": "FND-ABC789",
                "description": "Wallet funding via Bank Transfer",
                "status": "completed",
                "created_at": "2025-05-10T14:22:18.000000Z"
            }
        ]
    }
}
POST Fund Wallet
POST https://networkdatasub.com/api/wallet/fund

Initiates a funding request for the authenticated user's wallet.

Request Parameters

Parameter Type Description
amount Required number Amount to fund (min: 100, max: 1000000)
payment_method Required string Payment method (card, bank_transfer, ussd)
redirect_url Optional string URL to redirect after payment (for web integrations)
Request Example
Response Example
Request Example 
curl -X POST "https://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://networkdatasub.com/api/transactions

Returns a list of transactions for the authenticated user.

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://networkdatasub.com/api/transactions?page=1",
        "from": 1,
        "last_page": 5,
        "last_page_url": "https://networkdatasub.com/api/transactions?page=5",
        "next_page_url": "https://networkdatasub.com/api/transactions?page=2",
        "path": "https://networkdatasub.com/api/transactions",
        "per_page": 15,
        "prev_page_url": null,
        "to": 15,
        "total": 75
    }
}
GET Get Transaction Details
GET https://networkdatasub.com/api/transactions/{reference}

Returns detailed information about a specific transaction.

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

GET Get NIN Verification Pricing
GET https://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"
        }
    ]
}
POST Verify NIN
POST https://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://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="
        },
        "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
    }
}
GET Get BVN Verification Pricing
GET https://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://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://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": "idpass",
        "details": {
            "bvn": "12345678901",
            "firstName": "John",
            "lastName": "Doe",
            "middleName": "Smith",
            "dateOfBirth": "1990-01-01",
            "phoneNumber": "08012345678",
            "gender": "Male",
            "email": "[email protected]",
            "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
        },
        "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
    }
}
GET Get Verification History
GET https://networkdatasub.com/api/verification/nin/history
GET https://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://networkdatasub.com/api/verification/nin/{id}
GET https://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="
        }
    }
}