API Documentation

Overview

Welcome to the MyNin API. Our RESTful API provides secure and reliable access to NIN and BVN verification services.

Key Features

Real-time NIN and BVN verification
Multiple search methods (Number, Phone, Demographics)
Secure API key authentication
JSON request and response format
Comprehensive error handling
Wallet-based billing system

Important Notice

All API requests require user consent. You must include "consent": true in all verification requests. This ensures compliance with data protection regulations.

Authentication

All API requests must be authenticated using an API key. Include your API key in the request headers using one of the following methods:

Method 1: x-api-key Header

x-api-key: YOUR_API_KEY_HERE

Method 2: Authorization Bearer

Authorization: Bearer YOUR_API_KEY_HERE

How to Get Your API Key

Register an account on our platform
Login to your dashboard
Navigate to API Settings
Generate your API key
Fund your wallet to start making requests

Base URL

All API requests should be made to:

https://mynin.honeysub.com.ng/api

Request Format

All requests must be sent using the POST method with Content-Type: application/json.

Required Headers

Content-Type: application/json
x-api-key: YOUR_API_KEY_HERE

Request Body Structure

{
    "number": "12345678901",
    "consent": true
}

Consent Requirement

The "consent": true field is mandatory for all verification requests. Requests without this field will be rejected with a 400 error.

Response Format

All API responses are returned in JSON format with the following structure:

Successful Response

{
    "status": "success",
    "reportID": "280325-31AA4C4B87DC7A",
    "message": "ID Verified Successfully",
    "data": {
        "firstname": "EXAMPLE_FIRSTNAME",
        "middlename": "EXAMPLE_MIDDLENAME",
        "surname": "EXAMPLE_SURNAME",
        "telephoneno": "08012345678",
        "residence_state": "EXAMPLE_RESIDENT_STATE",
        "residence_town": "EXAMPLE_TOWN",
        "residence_address": "EXAMPLE_ADDRESS",
        "residence_lga": "EXAMPLE_LGA",
        "birthcountry": "EXAMPLE_COUNTRY",
        "birthstate": "EXAMPLE_STATE",
        "birthlga": "EXAMPLE_LGA",
        "gender": "EXAMPLE_GENDER",
        "nin": "12345678901",
        "birthdate": "1990-01-01",
        "photo": "EXAMPLE_BASE64_IMAGE_STRING"
    }
}

Error Response

{
    "status": "error",
    "message": "Invalid NIN format. NIN must be exactly 11 digits",
    "code": 400
}

API Endpoints

Available endpoints for verification services:

Endpoint	Method	Description	Price From
`/api/nin-verification`	POST	Verify NIN by number	₦150
`/api/nin-phone`	POST	Search NIN by phone number	₦200
`/api/nin-tracking`	POST	Search NIN by tracking ID	₦200
`/api/nin-demography`	POST	Search NIN by demographics	₦250
`/api/bvn-verification`	POST	Verify BVN by number	₦100
`/api/bvn-phone`	POST	Search BVN by phone number	₦150
`/api/balance`	GET	Check account balance	Free

NIN Verification POST

Verify a National Identity Number (NIN) and retrieve associated personal information.

Endpoint

POST https://mynin.honeysub.com.ng/api/nin-verification

Request Body

{
    "nin": "12345678901",
    "consent": true
}

cURL Example

curl -X POST https://mynin.honeysub.com.ng/api/nin-verification \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "nin": "12345678901",
    "consent": true
  }'

PHP Example

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://mynin.honeysub.com.ng/api/nin-verification",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => json_encode([
        "nin" => "12345678901",
        "consent" => true
    ]),
    CURLOPT_HTTPHEADER => array(
        "Content-Type: application/json",
        "x-api-key: YOUR_API_KEY_HERE"
    ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #:" . $err;
} else {
    $result = json_decode($response, true);
    print_r($result);
}
?>

JavaScript Example

fetch('https://mynin.honeysub.com.ng/api/nin-verification', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY_HERE'
    },
    body: JSON.stringify({
        nin: '12345678901',
        consent: true
    })
})
.then(response => response.json())
.then(data => {
    console.log('Success:', data);
})
.catch((error) => {
    console.error('Error:', error);
});

Successful Response

{
    "status": "success",
    "reportID": "NIN_251021154942_59E172",
    "message": "NIN Verified Successfully",
    "data": {
        "firstname": "JOHN",
        "middlename": "OLUMIDE",
        "surname": "ADEBAYO",
        "telephoneno": "08012345678",
        "residence_state": "LAGOS",
        "residence_town": "IKEJA",
        "residence_address": "15 ALLEN AVENUE",
        "residence_lga": "IKEJA",
        "birthcountry": "NIGERIA",
        "birthstate": "OGUN",
        "birthlga": "ABEOKUTA NORTH",
        "gender": "MALE",
        "nin": "12345678901",
        "birthdate": "1990-05-15",
        "photo": "data:image/jpeg;base64,/9j/4AAQSkZJ..."
    }
}

NIN Phone Search POST

Search for NIN information using a phone number.

Endpoint

POST https://mynin.honeysub.com.ng/api/nin-phone

Request Body

{
    "phone": "08012345678",
    "consent": true
}

cURL Example

curl -X POST https://mynin.honeysub.com.ng/api/nin-phone \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "phone": "08012345678",
    "consent": true
  }'

NIN Tracking POST

Search for NIN information using a tracking ID.

Request Body

{
    "tracking_id": "7Y0OG2ZO003KUPG",
    "consent": true
}

cURL Example

curl -X POST https://mynin.honeysub.com.ng/api/nin-tracking \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "tracking_id": "7Y0OG2ZO003KUPG",
    "consent": true
  }'

NIN Demography Search POST

Search for NIN information using demographic data.

Request Body

{
    "firstname": "JOHN",
    "lastname": "ADEBAYO",
    "gender": "male",
    "dob": "1990-05-15",
    "consent": true
}

cURL Example

curl -X POST https://mynin.honeysub.com.ng/api/nin-demography \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "firstname": "JOHN",
    "lastname": "ADEBAYO", 
    "gender": "male",
    "dob": "1990-05-15",
    "consent": true
  }'

BVN Verification POST

Verify a Bank Verification Number (BVN) and retrieve associated information.

Request Body

{
    "bvn": "22350591353",
    "consent": true
}

cURL Example

curl -X POST https://mynin.honeysub.com.ng/api/bvn-verification \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "bvn": "22350591353",
    "consent": true
  }'

Successful Response

{
    "status": "success",
    "reportID": "BVN_251019185403_3A7269",
    "message": "BVN Verified Successfully",
    "data": {
        "firstname": "JOHN",
        "middlename": "OLUMIDE", 
        "lastname": "ADEBAYO",
        "phone": "08012345678",
        "email": "john.adebayo@email.com",
        "bvn": "22350591353",
        "dob": "15-May-90",
        "gender": "Male",
        "state_of_origin": "Ogun",
        "state_of_residence": "Lagos",
        "nationality": "Nigerian",
        "photo": "data:image/jpeg;base64,/9j/4AAQSkZJ..."
    }
}

BVN Phone Search POST

Search for BVN information using a phone number.

Request Body

{
    "phone": "08012345678",
    "consent": true
}

cURL Example

curl -X POST https://mynin.honeysub.com.ng/api/bvn-phone \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "phone": "08012345678",
    "consent": true
  }'

Account Balance GET

Check your account balance and API usage statistics.

Endpoint

GET https://mynin.honeysub.com.ng/api/balance

cURL Example

curl -X GET https://mynin.honeysub.com.ng/api/balance \
  -H "x-api-key: YOUR_API_KEY_HERE"

Successful Response

{
    "status": "success",
    "reportID": null,
    "message": "Balance retrieved successfully",
    "data": {
        "user_id": 123,
        "username": "john_doe",
        "balance": 5000.00,
        "formatted_balance": "₦5,000.00",
        "user_type": "regular",
        "api_requests_today": 25,
        "api_limit": 1000
    }
}

Error Codes

The API uses standard HTTP status codes to indicate the success or failure of requests:

Status Code	Meaning	Description
200	OK	Request successful
400	Bad Request	Invalid request format or missing required fields
401	Unauthorized	Invalid or missing API key
403	Forbidden	API access disabled or insufficient permissions
405	Method Not Allowed	HTTP method not supported for this endpoint
429	Too Many Requests	Daily request limit exceeded
500	Internal Server Error	Server error occurred
503	Service Unavailable	Service temporarily unavailable

Common Error Examples

Missing Consent

{
    "status": "error",
    "message": "Consent is required. Please include \"consent\": true in your request",
    "code": 400
}

Invalid API Key

{
    "status": "error",
    "message": "Invalid API key",
    "code": 401
}

Insufficient Balance

{
    "status": "error",
    "message": "Insufficient wallet balance",
    "code": 400
}

Support

Need help with integration or have questions about our API? We're here to help!

WhatsApp Support

Get instant help from our technical team on WhatsApp.

Chat on WhatsApp

Email Support

Send us an email and we'll get back to you within 24 hours.

Send Email

Need Custom Integration?

Our team can help you integrate our API into your application. We offer:

Custom API wrappers for your programming language
Integration consulting and support
Bulk verification solutions
Webhook notifications
Priority technical support

Contact Sales Team

API Documentation

Contents

Overview

Key Features

Important Notice

Authentication

Method 1: x-api-key Header

Method 2: Authorization Bearer

How to Get Your API Key

Base URL

Request Format

Required Headers

Request Body Structure

Consent Requirement

Response Format

Successful Response

Error Response

API Endpoints

Endpoint

Request Body

cURL Example

PHP Example

JavaScript Example

Successful Response

Endpoint

Request Body

cURL Example

Request Body

cURL Example

Request Body

cURL Example

Request Body

cURL Example

Successful Response

Request Body

cURL Example

Endpoint

cURL Example

Successful Response

Error Codes

Common Error Examples

Missing Consent

Invalid API Key

Insufficient Balance

Support

WhatsApp Support

Email Support

Need Custom Integration?