API Documentation

Integrate NIN/BVN verification services into your application

REST API Secure Authentication Real-time Verification
Try it Live — API Sandbox

API Pricing

Below is the full list of all active NIN & BVN API endpoints along with their current pricing..

BVN Verification

₦150.00

Verify BVN number

NIN Demography Search

₦250.00

Search NIN using demographic data

NIN Phone Search

₦250.00

Search NIN using phone number

NIN Search

₦150.00

Search NIN using NIN number

Contents

Overview

Welcome to the NIN/BVN 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
  • Free browser-based API sandbox for live testing
Important Notice

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

API Sandbox — Try it Live

Test every endpoint of the CheckMyNINBVN API directly in your browser — no code required.

The sandbox is the fastest way to get started and the best place to debug integration issues. It sends real requests to the live API and shows you the actual response, so what works in the sandbox will work in your code.

What you can do in the sandbox

  • Validate your API key instantly — one click confirms whether your key works before you write a single line of code
  • Build and send requests to all endpoints with guided forms or raw JSON
  • See live responses with status codes, response times, and photo previews
  • Diagnose errors — every error comes with an actionable fix checklist
  • Copy working code in cURL, PHP, JavaScript, or Python, generated from your exact request
Getting "Invalid API key" in your code?

Use the sandbox's "Test my key" button first. It checks your key against the free balance endpoint and tells you exactly what's wrong — including hidden whitespace or copy-paste issues that cause most 401 errors.

Open the API Sandbox
Note

The sandbox calls the live API — successful requests to paid endpoints are billed to your wallet at normal rates. Free endpoints (/api/balance and /api/nin-modification-status) can be tested without any charge.

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
  1. Register an account on our platform
  2. Login to your dashboard
  3. Navigate to API Settings
  4. Generate your API key
  5. Fund your wallet to start making requests

Verify your key works in the sandbox before integrating.

Base URL

All API requests should be made to:

https://checkmyninbvn.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. Every endpoint can be tested live in the sandbox.

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
/api/nin-modification POST Submit NIN modification or validation order ₦6,000
/api/nin-modification-status GET / POST Check status of a NIN modification order Free
NIN Verification POST

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

Try this endpoint live in the sandbox
Endpoint
POST https://checkmyninbvn.com.ng/api/nin-verification
Request Body
{
    "nin": "12345678901",
    "consent": true
}
cURL Example
curl -X POST https://checkmyninbvn.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://checkmyninbvn.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://checkmyninbvn.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.

Try this endpoint live in the sandbox
Endpoint
POST https://checkmyninbvn.com.ng/api/nin-phone
Request Body
{
    "phone": "08012345678",
    "consent": true
}
cURL Example
curl -X POST https://checkmyninbvn.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.

Try this endpoint live in the sandbox
Request Body
{
    "tracking_id": "7Y0OG2ZO003KUPG",
    "consent": true
}
cURL Example
curl -X POST https://checkmyninbvn.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.

Try this endpoint live in the sandbox
Request Body
{
    "firstname": "JOHN",
    "lastname": "ADEBAYO",
    "gender": "male",
    "dob": "1990-05-15",
    "consent": true
}
cURL Example
curl -X POST https://checkmyninbvn.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.

Try this endpoint live in the sandbox
Request Body
{
    "bvn": "22350591353",
    "consent": true
}
cURL Example
curl -X POST https://checkmyninbvn.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.

Try this endpoint live in the sandbox
Request Body
{
    "phone": "08012345678",
    "consent": true
}
cURL Example
curl -X POST https://checkmyninbvn.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.

Try this endpoint live in the sandbox — it's free
Endpoint
GET https://checkmyninbvn.com.ng/api/balance
cURL Example
curl -X GET https://checkmyninbvn.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
    }
}
NIN Modification Orders POST

Submit a NIN modification or validation order for processing by our team. Orders are reviewed and processed within 24–48 hours. Your wallet is charged immediately upon submission.

Try this endpoint live in the sandbox
Endpoint
POST https://checkmyninbvn.com.ng/api/nin-modification
Service Types
service_type Description Required Fields Price
nin_name_modification Update name on NIN record nin, surname, firstname, phone_number, new_surname, new_firstname ₦16,000
nin_phone_modification Update phone on NIN record nin, surname, firstname, new_phone_number ₦16,000
nin_address_modification Update address on NIN record nin, surname, firstname, phone_number, new_address ₦16,000
nin_validation Validate NIN digits and DOB nin_digits, date_of_birth ₦6,000
Request Body — NIN Name Modification
{
    "service_type": "nin_name_modification",
    "nin": "12345678901",
    "surname": "ADEBAYO",
    "firstname": "JOHN",
    "middlename": "OLUMIDE",
    "phone_number": "08012345678",
    "new_surname": "ADEBAYO",
    "new_firstname": "JOHNSON",
    "new_middlename": "OLUMIDE",
    "consent": true
}
Request Body — NIN Phone Modification
{
    "service_type": "nin_phone_modification",
    "nin": "12345678901",
    "surname": "ADEBAYO",
    "firstname": "JOHN",
    "middlename": "OLUMIDE",
    "new_phone_number": "08099999999",
    "consent": true
}
Request Body — NIN Address Modification
{
    "service_type": "nin_address_modification",
    "nin": "12345678901",
    "surname": "ADEBAYO",
    "firstname": "JOHN",
    "middlename": "OLUMIDE",
    "phone_number": "08012345678",
    "new_address": "15 Allen Avenue, Ikeja, Lagos",
    "consent": true
}
Request Body — NIN Validation
{
    "service_type": "nin_validation",
    "nin_digits": "12345678901",
    "date_of_birth": "1990-05-15",
    "consent": true
}
cURL Example
curl -X POST https://checkmyninbvn.com.ng/api/nin-modification \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "service_type": "nin_name_modification",
    "nin": "12345678901",
    "surname": "ADEBAYO",
    "firstname": "JOHN",
    "phone_number": "08012345678",
    "new_surname": "ADEBAYO",
    "new_firstname": "JOHNSON",
    "consent": true
  }'
Successful Response
{
    "status": "success",
    "reportID": "NM_API_251021154942_59E172",
    "message": "NIN Name Modification order submitted successfully",
    "data": {
        "order_id": 45,
        "reference_id": "NM_API_251021154942_59E172",
        "service_type": "nin_name_modification",
        "service_name": "NIN Name Modification",
        "amount_charged": 16000,
        "status": "pending",
        "submitted_at": "2025-10-21 15:49:42",
        "note": "Your order has been received and is pending review. Use the reference_id to check status."
    }
}
Important Notes
  • Your wallet is charged immediately upon submission.
  • Orders are reviewed and processed within 24–48 hours.
  • Save the reference_id from the response to track your order status.
  • Rejected orders are automatically refunded to your wallet.
Check NIN Modification Order Status GET / POST

Check the processing status of a previously submitted NIN modification order using the reference_id returned at submission.

Try this endpoint live in the sandbox — it's free
Endpoint (GET)
GET https://checkmyninbvn.com.ng/api/nin-modification-status?reference_id=NM_API_251021154942_59E172
Endpoint (POST)
{
    "reference_id": "NM_API_251021154942_59E172"
}
cURL Example (GET)
curl -X GET "https://checkmyninbvn.com.ng/api/nin-modification-status?reference_id=NM_API_251021154942_59E172" \
  -H "x-api-key: YOUR_API_KEY_HERE"
Successful Response
{
    "status": "success",
    "reportID": "NM_API_251021154942_59E172",
    "message": "Order status retrieved successfully",
    "data": {
        "order_id": 45,
        "reference_id": "NM_API_251021154942_59E172",
        "service_type": "nin_name_modification",
        "service_name": "NIN Name Modification",
        "amount_charged": 16000.00,
        "status": "completed",
        "method": "api",
        "submitted_at": "2025-10-21 15:49:42",
        "updated_at": "2025-10-22 09:30:00",
        "completed_at": "2025-10-22 09:30:00",
        "notes": null,
        "status_detail": "Your order has been successfully completed."
    }
}
Order Status Values
Status Meaning
pending Order received, awaiting staff review
processing Order approved and being processed
approved Order approved, in final stage
completed Order fully completed
rejected Order rejected; wallet refunded automatically

Error Codes

The API uses standard HTTP status codes to indicate the success or failure of requests. If you hit an error you can't figure out, reproduce it in the sandbox — it explains every error with a fix checklist.

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
Invalid API Key
{
    "status": "error",
    "message": "Invalid API key",
    "code": 401
}

Getting this error? Use the "Test my key" button in the sandbox — it validates your key for free and detects the copy-paste issues that cause most 401 errors.

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!

Send a mail

info@checkmyninbvn.com.ng

Email Support

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

Send Email
Debug it yourself first

Most integration issues can be solved in minutes with the API sandbox — validate your key, reproduce your request, and get an instant diagnosis with working code to copy.

Open the API Sandbox
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

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

Send Email