Documentation Sections
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.
https://irust.ng.smartidea.com.ng/api/v1/bvn
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. |
POST /api/v1/bvn/crm HTTP/1.1
Host: 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 |
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:
/api/v1/bvn/banks
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.
curl -X GET "https://irust.ng.smartidea.com.ng/api/v1/bvn/banks" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"
{
"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": [...]
}
]
}
/api/v1/bvn/modification
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 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. |
curl -X POST "https://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"
}'
{
"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"
}
/api/v1/bvn/modification/status/{reference}
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). |
curl -X GET "https://irust.ng.smartidea.com.ng/api/v1/bvn/modification/status/BVM-1727702930-9AF1" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"
{
"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"
}
/api/v1/bvn/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. |
curl -X POST "https://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"
}'
{
"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"
}
/api/v1/bvn/crm/status/{reference}
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. |
curl -X GET "https://irust.ng.smartidea.com.ng/api/v1/bvn/crm/status/CRM-1727702950-84BC" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"
{
"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"
}
/api/v1/bvn/phone-search
Searches and retrieves registered Bank Verification Number (BVN) records matching a valid 11-digit Nigerian telephone number.
Request Body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
| phone_number | string | Required | 11-digit phone number (e.g. 08012345678). Accepts number as alias. |
| field_code | string | Optional | Service code (default: 45). |
curl -X POST "https://irust.ng.smartidea.com.ng/api/v1/bvn/phone-search" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"phone_number": "08034567890"
}'
{
"success": true,
"message": "BVN Phone search request submitted successfully.",
"reference": "BVS-1727702980-A4D2",
"phone_number": "08034567890",
"status": "processing",
"bvn": null,
"amount_charged": 500.00,
"comment": "Query sent to upstream provider"
}
/api/v1/bvn/phone-search/status/{reference}
Check the search resolution status. As soon as the search query completes upstream, the bvn key will be populated with the retrieved 11-digit Bank Verification Number.
| Identifier | Type | Required | Description |
|---|---|---|---|
| {reference} | string | Recommended | The unique reference returned when submitting search (e.g. BVS-1727702980-A4D2). |
| phone_number | string | Alternative | Pass in query string: ?phone_number=08034567890 to check latest record for that number. |
curl -X GET "https://irust.ng.smartidea.com.ng/api/v1/bvn/phone-search/status/BVS-1727702980-A4D2" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"
{
"success": true,
"reference": "BVS-1727702980-A4D2",
"service_type": "bvn_search",
"service_field": "BVN Phone Search",
"status": "successful",
"phone_number": "08034567890",
"bvn": "22233344455",
"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"
}
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.
/api/v1/bvn/status/{reference?}
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. |
curl -X GET "https://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://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
{
"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"
}
{
"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"
}
{
"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:
Request logged in ledger; awaiting upstream submission or review.
Dispatched upstream to NIBSS/partner bank for execution.
Completed successfully. Results, BVN, or verification documents ready.
Upstream returned clarification query or requires extra attestation.
Auto-Refund Triggered: Deducted amount is credited back to your wallet.
Administrative resolution applied and finalized.
Multi-Language Code Examples
curl -X POST "https://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://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://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://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();
curl -X GET "https://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://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://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://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. |