AMBVerify - REST API Documentation v1.0

SETUP & SECURITY

1. AMBVerify API Setup & Authentication

Identity Verification & Financial Management API for AMBVerify.

Setup:

Set base_url environment variable (e.g. https://ambverifyapp.com.ng or http://localhost:3000 for local testing)
Register or login — your secret API Key is generated and available in your User Dashboard / Admin Panel
All verification endpoints require a funded wallet

Master Base URL

API v1 Base Endpoint

https://ambverifyapp.com.ng/api/v1

Authentication Header

HTTP Request Header (Bearer Token)

Authorization: Bearer amb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

GET /api/v1/balance

2. Check Wallet Balance

Check your available NGN wallet balance programmatically before executing verification calls.

GET /api/v1/balance

// Response (200 OK)
{
  "status": true,
  "account_name": "Johnson Pay Nigeria",
  "email": "developer@johnsonpay.com.ng",
  "balance": 85000.00,
  "currency": "NGN"
}

SLIP INTEGRATION GUIDE

Visual Slip Delivery & Client Rendering

Our API can return both structured JSON citizen records and a complete printable visual slip encoded in Base64 and Data URI formats.

Notice: Visual Slip Delivery Requires Admin Approval

By default, new API accounts receive structured JSON data only. To unlock printable/renderable slips for your API calls, request approval from our engineering team via your account manager or WhatsApp. You can request slip access for NIN, BVN, Phone, and Demo searches independently. If your account has not been approved for slips yet, the verification will still succeed and deliver full citizen data, with "slip_available": false.

PHP Integration (cPanel, Laravel, WordPress)

In PHP, decode the slip_base64 string directly using native base64_decode() to output the complete styled document or save it as a file:

PHP Slip Consumer Example (cPanel / Laravel)

<?php
// Call AMBVerify API
$apiKey = "amb_live_xxxxxxxxxxxxxxxxxxxxxxxx";
$payload = json_encode([
    "documentType" => "NIN",
    "documentNumber" => "12345678901",
    "tier" => "Standard" // Options: Standard, Premium, Basic, Regular, VNIN
]);

$ch = curl_init("https://ambverifyapp.com.ng/api/v1/verify/nin");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer " . $apiKey
]);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

if (!empty($result['success'])) {
    // 1. Check if Admin has approved visual slips for your API account
    if (!empty($result['slip_available']) && !empty($result['slip_base64'])) {
        // Decode and render the full slip directly to user
        $slipHtml = base64_decode($result['slip_base64']);
        echo $slipHtml;
        exit;
    } else {
        // 2. Fallback: Display raw structured JSON data
        echo "Verification Successful: " . htmlspecialchars($result['data']['firstname']) . " " . htmlspecialchars($result['data']['surname']);
        echo "<br>NIN: " . htmlspecialchars($result['data']['nin']);
    }
} else {
    echo "Error: " . htmlspecialchars($result['message'] ?? 'Verification failed');
}
?>

JavaScript Integration (Browser Frontend & Node.js)

In JavaScript, you can render the slip without manual decoding by feeding slip_data_uri directly into an <iframe> or opening it in a new window, or decode slip_base64 in Node.js:

Frontend Browser JS (iframe / popup)

// Browser / Frontend Fetch
const res = await fetch("https://ambverifyapp.com.ng/api/v1/verify/nin", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer amb_live_xxxxxxxxxxxxxxxxxxxxxxxx"
  },
  body: JSON.stringify({
    documentNumber: "12345678901",
    tier: "Standard"
  })
});
const result = await res.json();

if (result.success) {
  if (result.slip_available && result.slip_data_uri) {
    // Option A: Embed directly into an iframe
    document.getElementById("slipFrame").src = result.slip_data_uri;

    // Option B: Open slip in a new tab for printing
    // window.open(result.slip_data_uri);
  } else {
    console.log("Citizen Data (Data-Only):", result.data);
  }
}

Node.js Backend (Express / Buffer decode)

// Node.js backend decoding
if (result.slip_available && result.slip_base64) {
  const html = Buffer.from(result.slip_base64, "base64").toString("utf-8");
  res.setHeader("Content-Type", "text/html");
  return res.send(html);
}

POST /api/v1/verify/nin

3. NIN Verification

Perform automated National Identification Number lookups. You can specify the desired slip format via the tier parameter: Standard, Premium, Basic, Regular, or VNIN. All slip types bill at the rate set in your Wholesale API configuration.

POST /api/v1/verify/nin — Request & Response

// Request
{
  "nin": "12345678901",
  "tier": "Standard"
}

// Response (When Slip Delivery is Approved by Admin)
{
  "success": true,
  "message": "NIN verified successfully",
  "slip_available": true,
  "slip_base64": "PCFET0NUWVBFIGh0bWw+PGh0bWwgbGFuZz0iZW4iPjxoZWFkPjxtZXRhIGNoYXJzZXQ9IlVURi04Ij4...",
  "slip_data_uri": "data:text/html;charset=utf-8;base64,PCFET0NUWVBFIGh0bWw+PGh0bWwgbGFuZz0iZW4iPjxoZWFkPjxtZXRh...",
  "data": {
    "firstname": "JOHNSON",
    "surname": "MICHAEL",
    "middlename": "DAVID",
    "nin": "12345678901",
    "dob": "1995-05-15",
    "gender": "Male",
    "phone": "08012345678",
    "address": "12 Sokode Crescent, Wuse Zone 5, Abuja",
    "stateOfResident": "FCT",
    "lga": "Municipal",
    "photo": "data:image/jpeg;base64,..."
  }
}

// Response (When Slip Delivery is NOT Approved — JSON Data Only)
{
  "success": true,
  "message": "NIN verified successfully",
  "slip_available": false,
  "slip_base64": null,
  "slip_notice": "Slip access for this service is not approved for your API account. Contact admin.",
  "data": {
    "firstname": "JOHNSON",
    "surname": "MICHAEL",
    "nin": "12345678901",
    "dob": "1995-05-15"
  }
}

POST /api/v1/verify/bvn

4. BVN Verification

Verify 11-digit Bank Verification Numbers instantly. Returns complete customer banking identity details. When approved by admin, includes printable Base64 BVN slip matching NIBSS formatting.

POST /api/v1/verify/bvn — Request & Response

// Request
{
  "bvn": "22233344455"
}

// Response
{
  "success": true,
  "message": "BVN verified successfully",
  "slip_available": true,
  "slip_base64": "PCFET0NUWVBFIGh0bWw+PGh0bWwgbGFuZz0iZW4iPjxoZWFkPjxtZXRh...",
  "slip_data_uri": "data:text/html;charset=utf-8;base64,PCFET0NUWVBFIGh0bWw...",
  "data": {
    "firstname": "MARY",
    "surname": "ADEBAYO",
    "bvn": "22233344455",
    "dob": "1992-11-20",
    "phone": "08098765432",
    "enrollmentBank": "Access Bank",
    "photo": "data:image/jpeg;base64,..."
  }
}

POST /api/v1/verify/phone

5. Phone Number Verification

Lookup citizen identity records using the linked 11-digit mobile number. When slip permission is active, delivers a printable NIN verification slip for that individual.

POST /api/v1/verify/phone — Request & Response

// Request
{
  "phone_number": "08012345678",
  "tier": "Standard"
}

// Response
{
  "success": true,
  "message": "PHONE verified successfully",
  "slip_available": true,
  "slip_base64": "PCFET0NUWVBFIGh0bWw+...",
  "slip_data_uri": "data:text/html;charset=utf-8;base64,...",
  "data": {
    "firstname": "AHMED",
    "surname": "BELLO",
    "nin": "55667788990",
    "phone": "08012345678"
  }
}

POST /api/v1/verify/demo

6. Demographic Verification

Search citizen identity records by demographic parameters (First Name, Surname, Date of Birth, and Gender). Delivers matched citizen record with optional base64 slip.

POST /api/v1/verify/demo — Request & Response

// Request
{
  "firstname": "JOHNSON",
  "lastname": "MICHAEL",
  "dob": "1995-05-15",
  "gender": "M",
  "tier": "Standard"
}

// Response
{
  "success": true,
  "message": "DEMO verified successfully",
  "slip_available": true,
  "slip_base64": "PCFET0NUWVBFIGh0bWw+...",
  "slip_data_uri": "data:text/html;charset=utf-8;base64,...",
  "data": {
    "firstname": "JOHNSON",
    "surname": "MICHAEL",
    "nin": "12345678901",
    "dob": "1995-05-15",
    "gender": "Male"
  }
}

POST /api/v1/jobs

7. Standard Validation

Submit standard validation jobs. Supported `serviceKey` values: `val_no_record`, `val_modification`, `val_vnin_sim`, `val_bank`, `val_photo_error`.

JSON Request Payload

{
  "serviceCategory": "Validation",
  "identifier": "12345678901",
  "serviceKey": "val_no_record",
  "submittedData": {
    "Validation Type": "No Record Found",
    "NIN": "12345678901",
    "Amount": "1500"
  }
}

POST /api/v1/jobs

8. Special Validation

Expedited priority validation. Supported `serviceKey` values: `special_val_no_record`, `special_val_modification`, `special_val_vnin_sim`, `special_val_bank`, `special_val_photo_error`.

JSON Request Payload

{
  "serviceCategory": "Special Validation",
  "identifier": "12345678901",
  "serviceKey": "special_val_no_record",
  "submittedData": {
    "Special Validation Type": "No Record Found",
    "NIN": "12345678901",
    "Amount": "3000"
  }
}

POST /api/v1/jobs

9. NIN Modification

Submit NIN data correction requests. Supported `serviceKey` values: `nin_mod_name`, `nin_mod_phone`, `nin_mod_dob`.

JSON Request Payload

{
  "serviceCategory": "NIN Modification",
  "identifier": "12345678901",
  "serviceKey": "nin_mod_name",
  "submittedData": {
    "Modification Field": "Name Modification",
    "Old Name": "Johnson Mike",
    "New Name": "Johnson Michael",
    "Amount": "1500"
  }
}

POST /api/v1/jobs

10. BVN Modification

Submit BVN data correction requests by Bank. Supported `serviceKey` values: `bvn_mod_agency_name`, `bvn_mod_agency_dob`, `bvn_mod_agency_phone`, `bvn_mod_firstbank_name`, `bvn_mod_gtb_name`, `bvn_mod_access_name`, `bvn_mod_uba_name`, `bvn_mod_zenith_name`.

JSON Request Payload

{
  "serviceCategory": "BVN Modification",
  "identifier": "22233344455",
  "serviceKey": "bvn_mod_gtb_name",
  "submittedData": {
    "Modification Field": "Name Modification",
    "First Bank or Agency": "Guaranty Trust Bank (GTB)",
    "New Surname": "Johnson",
    "New First Name": "Michael",
    "Amount": "6000"
  }
}

POST /api/v1/jobs

11. Backend Modification

Submit backend correction requests. Supported `serviceKey` values: `backend_mod_name`, `backend_mod_phone`, `backend_mod_gender`, `backend_dob_first_0_5`, `backend_dob_first_6_10`, `backend_dob_first_11_15`, `backend_dob_first_16_20`, `backend_dob_second_0_5`, `backend_dob_second_6_10`, `backend_dob_second_11_15`, `backend_dob_second_16_20`.

JSON Request Payload

{
  "serviceCategory": "Backend Modification",
  "identifier": "12345678901",
  "serviceKey": "backend_mod_name",
  "submittedData": {
    "Modification Category": "name",
    "New Details": "Correcting Surname spelling to Johnson",
    "Amount": "2000"
  }
}

POST /api/v1/jobs

12. Normal IPE Clearance

Submit standard Tracking ID clearance requests. Supported `serviceKey` values: `mod_ipe_normal`, `mod_ipe_hit`.

JSON Request Payload

{
  "serviceCategory": "Normal IPE",
  "identifier": "25441829000182",
  "serviceKey": "mod_ipe_normal",
  "submittedData": {
    "Clearance Type": "Normal IPE",
    "Tracking ID": "25441829000182",
    "Amount": "1000"
  }
}

POST /api/v1/jobs

13. Mod IPE Clearance

Submit modification IPE clearance requests. Supported `serviceKey` values: `mod_ipe_name`, `mod_ipe_dob`.

JSON Request Payload

{
  "serviceCategory": "Mod IPE",
  "identifier": "25441829000182",
  "serviceKey": "mod_ipe_name",
  "submittedData": {
    "Clearance Type": "Name Mod IPE",
    "Tracking ID": "25441829000182",
    "Amount": "1500"
  }
}

POST /api/v1/jobs

14. Data Delinking

Process ecosystem email/phone delinking requests. Supported `serviceKey` values: `delinking_delinking`, `delinking_both`, `delinking_retrieval`.

JSON Request Payload

{
  "serviceCategory": "Delinking",
  "identifier": "12345678901",
  "serviceKey": "delinking_both",
  "submittedData": {
    "Service Type": "both",
    "NIN Number": "12345678901",
    "Email Address": "johnson@example.com",
    "Amount": "3500"
  }
}

POST /api/v1/jobs

15. BVN Retrieval

Retrieve lost or forgotten BVN details by name and phone. Supported `serviceKey` value: `bvn_retrieval`.

JSON Request Payload

{
  "serviceCategory": "BVN Retrieval",
  "identifier": "08012345678",
  "serviceKey": "bvn_retrieval",
  "submittedData": {
    "First Name": "JOHNSON",
    "Middle Name": "DAVID",
    "Surname": "MICHAEL",
    "Phone Number": "08012345678",
    "Amount": "1000"
  }
}

WEBHOOK EVENT

16. Webhook Status Notifications

When an administrator processes your queued manual job, AMBVerify dispatches an automated HTTP POST payload to your saved Webhook URL.

Incoming Webhook JSON

{
  "event": "job.status_updated",
  "job_id": 104,
  "identifier": "12345678901",
  "service_category": "NIN Modification",
  "status": "Successful",
  "admin_reply": "Treated successfully. Record cleared.",
  "is_refunded": false,
  "refund_amount": 0,
  "timestamp": "2026-07-30T10:15:00.000Z"
}

Overview

Slip & Verification

Manual & Backend Queue

Webhooks

Become an API Partner

1. AMBVerify API Setup & Authentication

Setup:

2. Check Wallet Balance

Visual Slip Delivery & Client Rendering

Notice: Visual Slip Delivery Requires Admin Approval

PHP Integration (cPanel, Laravel, WordPress)

JavaScript Integration (Browser Frontend & Node.js)

3. NIN Verification

4. BVN Verification

5. Phone Number Verification

6. Demographic Verification

7. Standard Validation

8. Special Validation

9. NIN Modification

10. BVN Modification

11. Backend Modification

12. Normal IPE Clearance

13. Mod IPE Clearance

14. Data Delinking

15. BVN Retrieval

16. Webhook Status Notifications