BVN Services API Documentation v1.0 REST

Overview & Architecture

The BVN Services REST API provides automated endpoints for processing Bank Verification Number (BVN) modifications, Failed Enrolment CRM requests, Phone Number Search resolution, and Agent Enrolment onboarding. Every submission is recorded in an atomic ledger, assigned a trackable reference, and monitored in real-time.

Base Endpoint (Production)
https://www.irust.ng.smartidea.com.ng/api/v1/bvn
Data Format & Protocols
Strict HTTPS, JSON Request & Response bodies
Atomic Wallet & Auto-Refund: Your developer balance is charged only upon successful validation. If a submission is rejected by the upstream regulatory provider or administration, your account is immediately refunded and recorded in your ledger.

Authentication & Standard Headers

Every request must provide your developer API Token in the HTTP Authorization: Bearer header. Unauthenticated calls will receive HTTP 401 Unauthorized.

Header Value Required Description
Authorization Bearer <YOUR_API_TOKEN> Required Your personal secret developer token.
Content-Type application/json Required Declares JSON payload body for POST requests.
Accept application/json Required Ensures structured JSON response from server.
// Sample Header Set
POST /api/v1/bvn/crm HTTP/1.1
Host: www.irust.ng.smartidea.com.ng
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Accept: application/json

Service Fields & Pricing Matrix

Fees are dynamically calculated based on your account tier (user, agent, special, api).

Category Field Code Service Description Base Fee Turnaround Time
BVN Modification Bank-Based Services Available across all 20+ commercial and digital banks ending with BANK or BANKING. B01 Date of Birth (DOB) Modification ₦15,000.00 24 - 72 business hours
B02 Name Correction / Arrangement ₦3,500.00 24 - 48 business hours
B03 Phone Number Modification ₦2,500.00 24 - 48 business hours
B04 Gender / Marital Status Correction ₦2,500.00 24 - 48 business hours
B05 General BVN Modification / Address Info ₦2,500.00 24 - 48 business hours
Failed Enrolment CRM C01 NIBSS Validation Failure Resolution ₦1,500.00 15 - 60 minutes
C02 Biometric Exception / Fingerprint Mismatch ₦2,000.00 1 - 4 business hours
C03 Duplicate / System Collision Clearance ₦2,500.00 2 - 6 business hours
BVN Phone Search 45 Lookup BVN by Registered Phone Number ₦500.00 Instant / 5 - 15 minutes
Enrolment Agent 640 BVN Agency Enrolment Application ₦5,000.00 1 - 3 business days
Supported Enrolment Banks (Services ending with BANK / BANKING)
GET /api/v1/bvn/banks

BVN modifications in Nigeria are routed directly to the citizen's bank of enrollment. Pass any of the following bank names (or bank service ID) in the bank parameter:

ACCESS BANK FIRST BANK GT BANK ZENITH BANK UBA BANK FIDELITY BANK UNION BANK STANBIC IBTC BANK WEMA BANK STERLING BANK POLARIS BANK KEYSTONE BANK ECOBANK FCMB BANK JAIZ BANK TAJ BANK KUDA BANK OPAY DIGITAL BANKING PALMPAY BANKING MONIEPOINT BANK
GET /api/v1/bvn/banks
Bank Services Directory

Dynamically retrieve all active commercial and digital bank services (services ending with BANK or BANKING) along with their specific field codes, names, and fees tailored to your developer tier.

// Sample cURL Request
curl -X GET "https://www.irust.ng.smartidea.com.ng/api/v1/bvn/banks" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
// 200 OK Response
{
    "success": true,
    "message": "Supported BVN Modification banks and fields retrieved.",
    "total_banks": 20,
    "banks": [
        {
            "bank_id": 14,
            "bank_name": "ACCESS BANK",
            "description": "BVN data modification and enrolment servicing for ACCESS BANK.",
            "fields": [
                {
                    "field_id": 51,
                    "field_code": "B01",
                    "field_name": "Date of Birth (DOB) Modification",
                    "fee": 15000.00
                },
                {
                    "field_id": 52,
                    "field_code": "B02",
                    "field_name": "Name Correction / Arrangement",
                    "fee": 3500.00
                }
            ]
        },
        {
            "bank_id": 15,
            "bank_name": "FIRST BANK",
            "description": "BVN data modification and enrolment servicing for FIRST BANK.",
            "fields": [...]
        }
    ]
}
POST /api/v1/bvn/modification
Bank-Based Service

Submits a Bank Verification Number modification request routed directly to the citizen's enrolment bank according to NIBSS regulations. Supports base64 encoded affidavits or affidavit waiver surcharge.

Bank Routing: Every submission is billed and processed based on the bank provided.
Request Body (JSON)
Field Type Required Description
bank string | int Required Bank name (e.g. ACCESS BANK, FIRST BANK, GT BANK) or bank bank_id from /api/v1/bvn/banks.
bvn string Required 11-digit BVN to be modified.
nin string Required 11-digit National Identity Number.
field_code string Optional Field code (e.g. B01, B02). Defaults to B01.
description string Required Detailed description of requested modification.
affidavit string Optional available or not_available.
affidavit_file string Optional Base64 encoded PDF document if affidavit is available.
// Sample cURL Request
curl -X POST "https://www.irust.ng.smartidea.com.ng/api/v1/bvn/modification" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "bvn": "22233344455",
    "nin": "10020030040",
    "bank": "First Bank of Nigeria",
    "field_code": "B01",
    "description": "Correct spelling of last name from Ibrahim to Ibraheem",
    "affidavit": "available"
  }'
// 200 OK Response
{
    "success": true,
    "message": "BVN modification request submitted successfully.",
    "reference": "BVM-1727702930-9AF1",
    "bvn": "22233344455",
    "nin": "10020030040",
    "bank": "First Bank of Nigeria",
    "status": "pending",
    "amount_charged": 3500.00,
    "comment": "Pending administrative and NIBSS review"
}
GET POST also supported /api/v1/bvn/modification/status/{reference}
Status Synchronization

Check the live status, regulatory approval notes, updated details, and download link for any submitted BVN modification request using its reference.

Parameter Type Required Description
{reference} string Required The unique reference returned when submitting the modification (e.g. BVM-1727702930-9AF1).
// Sample cURL Status Request
curl -X GET "https://www.irust.ng.smartidea.com.ng/api/v1/bvn/modification/status/BVM-1727702930-9AF1" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
// 200 OK Completed Status Response
{
    "success": true,
    "reference": "BVM-1727702930-9AF1",
    "service_type": "bvn_modification",
    "service_field": "Change / Correction of Name",
    "status": "successful",
    "bvn": "22233344455",
    "nin": "10020030040",
    "bank": "First Bank of Nigeria",
    "comment": "Modification successfully approved and synced on NIBSS",
    "file_url": "https://arewasmart.com.ng/storage/results/bvn-mod-result.pdf",
    "amount": 3500.00,
    "created_at": "2026-10-01T10:15:20+01:00",
    "updated_at": "2026-10-01T10:45:00+01:00"
}
POST /api/v1/bvn/crm
Service: Failed Enrolment CRM

Submits a CRM request for failed NIBSS enrolment ticket and batch IDs to resolve enrollment collision, validation bottlenecks, or biometric exceptions.

Request Body (JSON)
Field Type Required Description
batch_id string Required Exactly 7-digit NIBSS Enrolment Batch ID (e.g. 1234567).
ticket_id string Required Exactly 8-digit NIBSS Enrolment Ticket ID (e.g. 12345678).
field_code string Optional CRM field category code (C01, C02, C03). Defaults to C01.
description string Optional Optional comment or error description from enrolment machine.
// Sample cURL Request
curl -X POST "https://www.irust.ng.smartidea.com.ng/api/v1/bvn/crm" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "batch_id": "7654321",
    "ticket_id": "98765432",
    "field_code": "C01"
  }'
// 200 OK Response
{
    "success": true,
    "message": "BVN CRM request submitted successfully.",
    "reference": "CRM-1727702950-84BC",
    "batch_id": "7654321",
    "ticket_id": "98765432",
    "status": "processing",
    "amount_charged": 1500.00,
    "comment": "Submitted for automated NIBSS CRM clearance"
}
GET POST also supported /api/v1/bvn/crm/status/{reference}
Status Synchronization

Check the live resolution status for any submitted CRM ticket. You can query either by the transaction reference or by passing the ticket_id and batch_id query parameters.

Identifier Type Required Description
{reference} string Recommended The unique reference returned when submitting CRM (e.g. CRM-1727702950-84BC).
ticket_id & batch_id string Alternative Pass in query string: ?ticket_id=98765432&batch_id=7654321 to look up by IDs.
// Sample cURL Status Request
curl -X GET "https://www.irust.ng.smartidea.com.ng/api/v1/bvn/crm/status/CRM-1727702950-84BC" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
// 200 OK Resolved CRM Status Response
{
    "success": true,
    "reference": "CRM-1727702950-84BC",
    "service_type": "CRM",
    "service_field": "NIBSS Validation Failure Resolution",
    "status": "successful",
    "ticket_id": "98765432",
    "batch_id": "7654321",
    "comment": "CRM ticket resolved. Biometric exception cleared on NIBSS.",
    "file_url": null,
    "amount": 1500.00,
    "created_at": "2026-10-01T10:20:15+01:00",
    "updated_at": "2026-10-01T10:35:40+01:00"
}
BVN Enrolment Agent (Manual Portal Service)

Please note that BVN Enrolment Agent onboarding is a manual administrative desk service requiring regulatory bank documentation, compliance clearance, and physical device assignment. It is submitted directly via the Agent Portal Form and is not processed via an automated REST API.

GET POST also supported /api/v1/bvn/status/{reference?}
Real-Time Audit (Free) Auto-Refund Guaranteed

The unified BVN Status Audit Endpoint provides real-time polling, upstream status synchronization, and outcome retrieval for all BVN operations (Modification, Failed Enrolment CRM, Phone Search, and Agent Applications). If an upstream provider updates or rejects a request, our engine immediately synchronizes the record and credits any eligible auto-refund back to your developer wallet.

Supported Query Identifiers
Lookup Method Format Applies To Description
URL Path {reference} /api/v1/bvn/status/<REF> All Services Universal transaction reference (e.g. BVM-..., CRM-..., BVS-...).
Query: ?reference=... /api/v1/bvn/status?reference=<REF> All Services Passed via query string or in JSON body {"reference": "<REF>"}.
Query: ?ticket_id=&batch_id= ?ticket_id=12345678&batch_id=1234567 Failed Enrolment CRM Audits status using official NIBSS 8-digit ticket and 7-digit batch IDs.
Query: ?phone_number=... /api/v1/bvn/status?phone_number=080... BVN Phone Search Audits latest search request initiated for this 11-digit phone number.
Query: ?bvn=... /api/v1/bvn/status?bvn=222... BVN Modification Audits latest modification record logged for this 11-digit BVN.
// Method 1: GET request by Path Reference
curl -X GET "https://www.irust.ng.smartidea.com.ng/api/v1/bvn/status/BVM-1727702930-9AF1" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

// Method 2: POST request with JSON Payload
curl -X POST "https://www.irust.ng.smartidea.com.ng/api/v1/bvn/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"reference": "CRM-1727702950-84BC"}'
Live 200 OK Response Schemas by Service
// BVN Modification Status Check (Approved)
{
    "success": true,
    "reference": "BVM-1727702930-9AF1",
    "service_type": "bvn_modification",
    "service_field": "Change / Correction of Name",
    "status": "successful",
    "bvn": "22233344455",
    "nin": "10020030040",
    "bank": "First Bank of Nigeria",
    "phone_number": null,
    "ticket_id": null,
    "batch_id": null,
    "comment": "Modification successfully approved and synced on NIBSS",
    "file_url": "https://arewasmart.com.ng/storage/results/bvn-mod-result.pdf",
    "amount": 3500.00,
    "created_at": "2026-10-01T10:15:20+01:00",
    "updated_at": "2026-10-01T10:45:00+01:00"
}
// Failed Enrolment CRM Status Check (Resolved)
{
    "success": true,
    "reference": "CRM-1727702950-84BC",
    "service_type": "CRM",
    "service_field": "NIBSS Validation Failure Resolution",
    "status": "successful",
    "bvn": null,
    "nin": null,
    "bank": null,
    "phone_number": null,
    "ticket_id": "98765432",
    "batch_id": "7654321",
    "comment": "CRM ticket resolved. Biometric exception cleared on NIBSS.",
    "file_url": null,
    "amount": 1500.00,
    "created_at": "2026-10-01T10:20:15+01:00",
    "updated_at": "2026-10-01T10:35:40+01:00"
}
// BVN Phone Search Status Check (Resolved & BVN Retrieved)
{
    "success": true,
    "reference": "BVS-1727702980-A4D2",
    "service_type": "bvn_search",
    "service_field": "BVN Phone Search",
    "status": "successful",
    "bvn": "22233344455",
    "nin": null,
    "bank": null,
    "phone_number": "08034567890",
    "ticket_id": null,
    "batch_id": null,
    "comment": "BVN record resolved successfully.",
    "file_url": null,
    "amount": 500.00,
    "created_at": "2026-10-01T10:40:00+01:00",
    "updated_at": "2026-10-01T10:42:15+01:00"
}
Response Field Dictionary
Field Type Description
success boolean true when record is located and audited.
reference string Unique trackable transaction reference.
service_type string Service identifier (bvn_modification, CRM, bvn_search, bvn_user).
service_field string Human-readable service title and field name.
status string Current lifecycle status (pending, processing, successful, failed, rejected, query).
bvn string | null The 11-digit BVN. For Phone Search, contains the discovered BVN upon completion.
phone_number string | null Registered telephone number queried in BVN Phone Search.
ticket_id & batch_id string | null NIBSS Enrolment ticket ID (8 digits) and batch ID (7 digits) for CRM requests.
comment string | null Upstream regulatory feedback, clearance notes, or administrative review summary.
file_url string | null Direct download URL for generated outcome PDF slip or regulatory clearance letter.
amount float Amount in Naira (₦) billed for the transaction. Automatically refunded if failed/rejected.
created_at & updated_at string ISO 8601 timestamps of submission and last status update.

Status Lifecycle & Refund Guarantee

Every request progresses deterministically through official operational states:

pending

Request logged in ledger; awaiting upstream submission or review.

processing

Dispatched upstream to NIBSS/partner bank for execution.

successful

Completed successfully. Results, BVN, or verification documents ready.

query

Upstream returned clarification query or requires extra attestation.

failed / rejected

Auto-Refund Triggered: Deducted amount is credited back to your wallet.

resolved

Administrative resolution applied and finalized.

Multi-Language Code Examples

# Submit BVN CRM Request
curl -X POST "https://www.irust.ng.smartidea.com.ng/api/v1/bvn/crm" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "batch_id": "7654321",
    "ticket_id": "98765432",
    "field_code": "C01"
  }'
<?php

$client = new \GuzzleHttp\Client();

$response = $client->post('https://www.irust.ng.smartidea.com.ng/api/v1/bvn/crm', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_TOKEN',
        'Content-Type'  => 'application/json',
        'Accept'        => 'application/json',
    ],
    'json' => [
        'batch_id'   => '7654321',
        'ticket_id'  => '98765432',
        'field_code' => 'C01',
    ],
]);

$result = json_decode($response->getBody(), true);
echo "Reference: " . $result['reference'];
import requests

url = "https://www.irust.ng.smartidea.com.ng/api/v1/bvn/crm"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
    "batch_id": "7654321",
    "ticket_id": "98765432",
    "field_code": "C01"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print("Reference:", data.get("reference"))
const axios = require('axios');

async function submitBvnCrm() {
    try {
        const response = await axios.post('https://www.irust.ng.smartidea.com.ng/api/v1/bvn/crm', {
            batch_id: '7654321',
            ticket_id: '98765432',
            field_code: 'C01'
        }, {
            headers: {
                'Authorization': 'Bearer YOUR_API_TOKEN',
                'Content-Type': 'application/json',
                'Accept': 'application/json'
            }
        });

        console.log('Submission Success:', response.data);
    } catch (error) {
        console.error('Submission Failed:', error.response?.data || error.message);
    }
}

submitBvnCrm();
# Check BVN Status by Reference
curl -X GET "https://www.irust.ng.smartidea.com.ng/api/v1/bvn/status/BVM-1727702930-9AF1" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
<?php

$client = new \GuzzleHttp\Client();

$reference = 'BVM-1727702930-9AF1';
$response = $client->get("https://www.irust.ng.smartidea.com.ng/api/v1/bvn/status/{$reference}", [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_TOKEN',
        'Accept'        => 'application/json',
    ],
]);

$result = json_decode($response->getBody(), true);
echo "Status: " . $result['status'] . PHP_EOL;
echo "BVN: " . ($result['bvn'] ?? 'Processing') . PHP_EOL;
import requests

reference = "BVM-1727702930-9AF1"
url = f"https://www.irust.ng.smartidea.com.ng/api/v1/bvn/status/{reference}"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
data = response.json()
print("Status:", data.get("status"))
print("BVN:", data.get("bvn"))
print("Comment:", data.get("comment"))
const axios = require('axios');

async function checkBvnStatus(reference) {
    try {
        const response = await axios.get(`https://www.irust.ng.smartidea.com.ng/api/v1/bvn/status/${reference}`, {
            headers: {
                'Authorization': 'Bearer YOUR_API_TOKEN',
                'Accept': 'application/json'
            }
        });

        console.log('Status Result:', response.data);
    } catch (error) {
        console.error('Status Check Failed:', error.response?.data || error.message);
    }
}

checkBvnStatus('BVM-1727702930-9AF1');

HTTP Status & Error Codes

The API utilizes standard HTTP response codes to communicate errors:

HTTP Code Title Reason / Action
200 OK Success Request received, processed, or successfully queued.
400 Bad Request Invalid Parameter Missing or invalid parameter format (e.g. non-11 digit BVN or wrong ticket ID length).
401 Unauthorized Authentication Failed Missing, inactive, or invalid Bearer API token.
402 Payment Required Insufficient Balance Developer wallet balance is lower than the fee required for the service. Fund your wallet.
422 Unprocessable Validation Exception JSON validation failed against payload rules.
500 Server Error Internal Failure Upstream communication error. The system will auto-retry or preserve status for administrator check.
NIN TRUST
Please wait ...

Securing your session