NIN TRUST - Portal

Overview & Architecture

The Arewa Verification API provides ultra-fast, bank-grade identity verification infrastructure for Nigerian software applications, fintechs, aggregators, and enterprise portals. Authenticate citizens in real-time against authoritative government sources with 99.9% uptime.

Production Base URL https://www.irust.ng.smartidea.com.ng/api/v1

Authentication

All API requests must be transmitted over secure HTTPS and authenticated using your secret API key. You can provide your key through either of the following standard HTTP headers:

Option 1: Bearer Token (Recommended)

Standard Authorization HTTP header with Bearer prefix.

Authorization: Bearer YOUR_API_KEY

Option 2: Custom Header

Pass your token directly in the X-API-KEY header.

X-API-KEY: YOUR_API_KEY

Keep your secret API keys confidential. Do not expose them in public GitHub repositories or front-end client-side JavaScript.

Service Pricing & Automatic Billing

API requests operate on a prepaid wallet balance model. Fees are deducted atomically only when an upstream verification is completely successful. If a record is not found or the query fails, no fee is charged.

Service Name	Service Code	Base Fee	Response Time	Billing Trigger
BVN Verification	600	₦70.00	~1.2s	On 200 OK + Valid Profile
NIN Direct Verification	610	₦80.00	~1.5s	On 200 OK + Valid Profile
NIN via Phone Lookup	615	₦100.00	~2.0s	On 200 OK + Valid Profile
NIN Demographic Search	620	₦100.00	~2.2s	On 200 OK + Match Found
Fast v2 (Zero-Downtime Alternative Engines)
BVN Verification (Fast v2) v2 Engine	V600	₦100.00	~0.8s (Fast)	On 200 OK + Valid Profile (Alternative Gateway)
NIN Direct Verification (Fast v2) v2 Engine	V610	₦150.00	~0.9s (Fast)	On 200 OK + Valid Profile (Alternative Gateway)
NIN via Phone Lookup (Fast v2) v2 Engine	V105	₦100.00	~1.0s (Fast)	On 200 OK + Valid Profile (Alternative Gateway)

POST /api/v1/verification/bvn

BVN Verification

Verifies an 11-digit Bank Verification Number and retrieves validated banking profile data including customer photo, full names, phone number, and residential details.

Request Body (JSON)

Field	Type	Required	Description
`bvn`	string	Required	The 11-digit BVN to verify (e.g. `"22222222222"`).

Example Request

{
  "bvn": "22222222222"
}

200 OK Response

{
  "status": "success",
  "message": "BVN verified successfully.",
  "reference": "VER_20260925120000_A1B2",
  "amount_charged": 70,
  "wallet_balance": 4930,
  "data": {
    "bvn": "22222222222",
    "firstName": "MUSA",
    "lastName": "BELLO",
    "middleName": "IBRAHIM",
    "gender": "Male",
    "dateOfBirth": "1992-05-14",
    "phoneNumber": "08031234567",
    "state": "Kano",
    "photo": "base64_string..."
  }
}

POST /api/v1/verification/nin

NIN Direct Verification

Direct lookup of a National Identity Number against the NIMC national registry. Returns verified biometric photo, names, telephone, birthdate, and registration details.

Request Body (JSON)

Field	Type	Required	Description
`nin`	string	Required	The 11-digit citizen NIN number.

Example Request

{
  "nin": "12345678901"
}

200 OK Response

{
  "status": "success",
  "message": "NIN verified successfully.",
  "reference": "VER_20260925120531_F7C9",
  "amount_charged": 80,
  "wallet_balance": 4850,
  "data": {
    "nin": "12345678901",
    "firstName": "FATIMA",
    "lastName": "SULEIMAN",
    "middleName": "AISHA",
    "gender": "Female",
    "dateOfBirth": "1995-11-20",
    "phoneNumber": "08123456789",
    "state": "Kaduna",
    "lga": "Zaria",
    "photo": "base64_string...",
    "trackingId": "TRK987654321"
  }
}

POST /api/v1/verification/nin-phone

NIN via Phone Lookup

Locates and retrieves the full National Identity Number record linked to an enrolled Nigerian mobile telephone number.

Request Body (JSON)

Field	Type	Required	Description
`phone_number`	string	Required	11-digit Nigerian telephone number (e.g. `"08031234567"`).

Example Request

{
  "phone_number": "08031234567"
}

200 OK Response

{
  "status": "success",
  "message": "NIN verified successfully via telephone number.",
  "reference": "VER_20260925121045_D3E1",
  "amount_charged": 100,
  "wallet_balance": 4750,
  "data": {
    "nin": "12345678901",
    "firstName": "ALIYU",
    "lastName": "ABUBAKAR",
    "gender": "Male",
    "dateOfBirth": "1988-03-12",
    "phoneNumber": "08031234567",
    "photo": "base64_string..."
  }
}

POST /api/v1/verification/nin-demographic

NIN Demographic Search

Verifies and retrieves citizen NIN by matching demographic fields: First Name, Last Name, Gender, and Date of Birth.

Request Body (JSON)

Field	Type	Required	Description
`first_name`	string	Required	Citizen's official first name.
`last_name`	string	Required	Citizen's surname / last name.
`gender`	string	Required	`"M"` or `"F"` (or male/female).
`dob`	string	Required	Date of birth format `DD-MM-YYYY`.

Example Request

{
  "first_name": "AHMAD",
  "last_name": "GARBA",
  "gender": "M",
  "dob": "14-06-1990"
}

200 OK Response

{
  "status": "success",
  "message": "NIN Demographic Verification successful.",
  "reference": "VER_20260925121512_K9L2",
  "is_suspended": false,
  "amount_charged": 100,
  "wallet_balance": 4650,
  "data": {
    "nin": "12345678901",
    "firstName": "AHMAD",
    "lastName": "GARBA",
    "gender": "M",
    "dateOfBirth": "14-06-1990",
    "photo": "base64_string..."
  }
}

POST /api/v1/verification/bvn-v2

BVN Fast v2 Code: V600

Zero-Downtime Engine Standard / Premium / Plastic Slips

High-speed alternative endpoint for BVN validation. Connects directly to failover identity gateways to prevent verification timeouts. Returns comprehensive citizen biodata, enrollment photo, date of birth, phone number, and residential address.

Request Body (JSON)

Field	Type	Required	Description
`bvn`	string	Required	The 11-digit Bank Verification Number starting with 22 (e.g. `"22222222222"`).

Example Request

{
  "bvn": "22222222222"
}

200 OK Response

{
  "status": "success",
  "message": "BVN (v2) verified successfully.",
  "reference": "VER_20261023120000_V600",
  "amount_charged": 100,
  "wallet_balance": 4900,
  "service_type": "BVN",
  "version": "v2",
  "data": {
    "bvn": "22222222222",
    "firstName": "MUSA",
    "lastName": "BELLO",
    "middleName": "IBRAHIM",
    "gender": "Male",
    "dateOfBirth": "1992-05-14",
    "phoneNumber": "08031234567",
    "state": "Kano",
    "photo": "base64_string..."
  }
}

Slip Downloads Available

Slip generation remains identical to standard BVN. You can download slips via the portal or direct endpoint: /verification/bvn-v2/download-slip/{verification_id}?type=standard|premium|plastic.

POST /api/v1/verification/nin-v2

NIN Direct Fast v2 Code: V610

Zero-Downtime Engine Regular / Standard / Premium / VNIN Slips

Alternative direct National Identity Number lookup powered by the secondary v2 NIMC identity node. Provides uninterrupted verification access even during peak traffic periods with high availability and quick ~0.9s response latency.

Request Body (JSON)

Field	Type	Required	Description
`nin`	string	Required	The 11-digit citizen National Identity Number (e.g. `"12345678901"`).

Example Request

{
  "nin": "12345678901"
}

200 OK Response

{
  "status": "success",
  "message": "NIN (v2) verified successfully.",
  "reference": "VER_20261023120531_V610",
  "amount_charged": 150,
  "wallet_balance": 4750,
  "service_type": "NIN",
  "version": "v2",
  "data": {
    "nin": "12345678901",
    "firstName": "FATIMA",
    "lastName": "SULEIMAN",
    "middleName": "AISHA",
    "gender": "Female",
    "dateOfBirth": "1995-11-20",
    "phoneNumber": "08123456789",
    "state": "Kaduna",
    "lga": "Zaria",
    "photo": "base64_string...",
    "trackingId": "TRK987654321"
  }
}

Slip Downloads Available

Slip templates remain fully compatible. Download regular, standard, premium, or vnin slips via: /verification/nin-v2/download-slip/{verification_id}?type=regular|standard|premium|vnin.

POST /api/v1/verification/nin-phone-v2

NIN Phone Fast v2 Code: V105

Zero-Downtime Engine Regular / Standard / Premium / VNIN Slips

Retrieves citizen National Identity Number records using their enrolled Nigerian mobile phone number through the high-availability secondary cluster. Accepts either phone_number or phone parameter.

Request Body (JSON)

Field	Type	Required	Description
`phone_number`	string	Required	11-digit Nigerian telephone number (e.g. `"08031234567"`). Also accepts `phone`.

Example Request

{
  "phone_number": "08031234567"
}

200 OK Response

{
  "status": "success",
  "message": "NIN (v2) verified successfully via telephone number.",
  "reference": "VER_20261023121045_V105",
  "amount_charged": 100,
  "wallet_balance": 4650,
  "service_type": "NIN_PHONE",
  "version": "v2",
  "data": {
    "nin": "12345678901",
    "firstName": "ALIYU",
    "lastName": "ABUBAKAR",
    "middleName": "SANI",
    "gender": "Male",
    "dateOfBirth": "1988-03-12",
    "phoneNumber": "08031234567",
    "state": "Kano",
    "lga": "Nassarawa",
    "photo": "base64_string..."
  }
}

Slip Downloads Available

Slip templates remain fully compatible. Download regular, standard, premium, or vnin slips via: /verification/nin-phone-v2/download-slip/{verification_id}?type=regular|standard|premium|vnin.

GET /api/v1/verification/status/{reference}

Status Audit

Check the live transaction status, charge details, and record audit for any previous verification reference.

{ "status": "success", "data": { "reference": "VER_20260925120000_A1B2", "verification_status": "successful", "service_type": "BVN", "amount": 70, "verified_name": "MUSA IBRAHIM BELLO", "submission_date": "2026-09-25T11:00:00.000000Z", "transaction": { "reference": "VER_20260925120000_A1B2", "status": "successful", "type": "debit", "amount": 70, "balance_before": 5000, "balance_after": 4930, "created_at": "2026-09-25T11:00:00.000000Z" } } }

GET /api/v1/user/balance

Account Balance

Retrieve current wallet balance, currency, and account status for automated billing monitoring and low-balance warnings.

{ "status": "success", "data": { "user": { "name": "Acme Technologies", "email": "developer@acme.com", "role": "business" }, "wallet": { "currency": "NGN", "balance": 45000.5, "available_balance": 45000.5, "status": "active" } } }

Code Implementation Examples

Select an endpoint and language to preview copy-ready production code.

POST /api/v1/verification/bvn-v2 Field Code: V600

curl --location --request POST 'https://www.irust.ng.smartidea.com.ng/api/v1/verification/bvn-v2' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "bvn": "22222222222"
}'

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_KEY')
    ->acceptJson()
    ->post('https://www.irust.ng.smartidea.com.ng/api/v1/verification/bvn-v2', [
        'bvn' => '22222222222',
    ]);

if ($response->successful()) {
    $data = $response->json('data');
    echo "BVN Verified: " . $data['firstName'] . " " . $data['lastName'];
} else {
    echo "Verification Failed: " . $response->json('message');
}

import requests

url = "https://www.irust.ng.smartidea.com.ng/api/v1/verification/bvn-v2"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
    "bvn": "22222222222"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const axios = require('axios');

async function verifyBvnFastV2(bvn) {
  try {
    const res = await axios.post('https://www.irust.ng.smartidea.com.ng/api/v1/verification/bvn-v2', {
      bvn: bvn
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Accept': 'application/json'
      }
    });
    console.log('Success:', res.data);
  } catch (err) {
    console.error('Error:', err.response?.data || err.message);
  }
}

verifyBvnFastV2('22222222222');

POST /api/v1/verification/nin-v2 Field Code: V610

curl --location --request POST 'https://www.irust.ng.smartidea.com.ng/api/v1/verification/nin-v2' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "nin": "12345678901"
}'

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_KEY')
    ->acceptJson()
    ->post('https://www.irust.ng.smartidea.com.ng/api/v1/verification/nin-v2', [
        'nin' => '12345678901',
    ]);

if ($response->successful()) {
    $data = $response->json('data');
    echo "NIN Verified: " . $data['firstName'] . " " . $data['lastName'];
} else {
    echo "Verification Failed: " . $response->json('message');
}

import requests

url = "https://www.irust.ng.smartidea.com.ng/api/v1/verification/nin-v2"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
    "nin": "12345678901"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const axios = require('axios');

async function verifyNinFastV2(nin) {
  try {
    const res = await axios.post('https://www.irust.ng.smartidea.com.ng/api/v1/verification/nin-v2', {
      nin: nin
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Accept': 'application/json'
      }
    });
    console.log('Success:', res.data);
  } catch (err) {
    console.error('Error:', err.response?.data || err.message);
  }
}

verifyNinFastV2('12345678901');

POST /api/v1/verification/nin-phone-v2 Field Code: V105

curl --location --request POST 'https://www.irust.ng.smartidea.com.ng/api/v1/verification/nin-phone-v2' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "phone_number": "08031234567"
}'

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_KEY')
    ->acceptJson()
    ->post('https://www.irust.ng.smartidea.com.ng/api/v1/verification/nin-phone-v2', [
        'phone_number' => '08031234567',
    ]);

if ($response->successful()) {
    $data = $response->json('data');
    echo "NIN Linked via Phone: " . $data['firstName'] . " " . $data['lastName'];
} else {
    echo "Verification Failed: " . $response->json('message');
}

import requests

url = "https://www.irust.ng.smartidea.com.ng/api/v1/verification/nin-phone-v2"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
    "phone_number": "08031234567"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const axios = require('axios');

async function verifyNinPhoneFastV2(phoneNumber) {
  try {
    const res = await axios.post('https://www.irust.ng.smartidea.com.ng/api/v1/verification/nin-phone-v2', {
      phone_number: phoneNumber
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Accept': 'application/json'
      }
    });
    console.log('Success:', res.data);
  } catch (err) {
    console.error('Error:', err.response?.data || err.message);
  }
}

verifyNinPhoneFastV2('08031234567');

POST /api/v1/verification/bvn Field Code: 600

curl --location --request POST 'https://www.irust.ng.smartidea.com.ng/api/v1/verification/bvn' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "bvn": "22222222222"
}'

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_KEY')
    ->acceptJson()
    ->post('https://www.irust.ng.smartidea.com.ng/api/v1/verification/bvn', [
        'bvn' => '22222222222',
    ]);

if ($response->successful()) {
    $data = $response->json('data');
    echo "Citizen Name: " . $data['firstName'] . " " . $data['lastName'];
} else {
    echo "Verification Error: " . $response->json('message');
}

import requests

url = "https://www.irust.ng.smartidea.com.ng/api/v1/verification/bvn"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
    "bvn": "22222222222"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const axios = require('axios');

async function verifyBVN(bvn) {
  try {
    const res = await axios.post('https://www.irust.ng.smartidea.com.ng/api/v1/verification/bvn', {
      bvn: bvn
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Accept': 'application/json'
      }
    });
    console.log('Result:', res.data);
  } catch (err) {
    console.error('Failed:', err.response?.data || err.message);
  }
}

verifyBVN('22222222222');

POST /api/v1/verification/nin Field Code: 610

curl --location --request POST 'https://www.irust.ng.smartidea.com.ng/api/v1/verification/nin' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "nin": "12345678901"
}'

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_KEY')
    ->acceptJson()
    ->post('https://www.irust.ng.smartidea.com.ng/api/v1/verification/nin', [
        'nin' => '12345678901',
    ]);

if ($response->successful()) {
    $data = $response->json('data');
    echo "Citizen Name: " . $data['firstName'] . " " . $data['lastName'];
} else {
    echo "Verification Error: " . $response->json('message');
}

import requests

url = "https://www.irust.ng.smartidea.com.ng/api/v1/verification/nin"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
    "nin": "12345678901"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const axios = require('axios');

async function verifyNIN(nin) {
  try {
    const res = await axios.post('https://www.irust.ng.smartidea.com.ng/api/v1/verification/nin', {
      nin: nin
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Accept': 'application/json'
      }
    });
    console.log('Result:', res.data);
  } catch (err) {
    console.error('Failed:', err.response?.data || err.message);
  }
}

verifyNIN('12345678901');

HTTP Status & Error Codes

HTTP Status	Meaning	Description / Remediation
200 OK	Success	Verification completed and authoritative citizen details returned.
400 Bad Request	Provider / Query Failure	Upstream provider returned an error or identity record was not found.
401 Unauthorized	Invalid API Key	API key is missing or invalid. Check your Bearer token in header.
402 Payment Required	Insufficient Balance	Your wallet has insufficient funds to cover the service fee. Deposit funds.
422 Unprocessable	Validation Error	Request payload failed validation (e.g. BVN is not 11 numeric digits).
504 Gateway Timeout	Upstream Timeout	Government identity gateway is slow or experiencing a temporary outage.

Verification API Documentation v1.0 REST

Documentation Sections

Overview & Architecture

Authentication

Service Pricing & Automatic Billing

Request Body (JSON)

Request Body (JSON)

Request Body (JSON)

Request Body (JSON)

Fast v2 Identity Verification Suite (Zero-Downtime)

Request Body (JSON)

Slip Downloads Available

Request Body (JSON)

Slip Downloads Available

Request Body (JSON)

Slip Downloads Available

Code Implementation Examples

HTTP Status & Error Codes