API Integration Guide

Setup

Create a Hadi Verify API key from API access. Send it as a bearer token from your server. Keep it out of public browser code.

Base URL: https://hadiverify.com.ng/api.php

Requests use JSON with Content-Type: application/json. HTTPS is required for production.

Provider credentials are managed server-side by Hadi Verify. API consumers only need their Hadi Verify API key.

Requests to NIN, BVN, IPE, and validation endpoints may debit your wallet. Use only identity information you are authorized to verify.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Available verification slips

Prices below are system defaults. Admin overrides are version-specific; authenticated GET v1/services returns your account's effective prices.

NIN Verify V1

Slip	Supported lookup methods	System prices
Regular	NIN, phone, demographic	NIN NGN 150.00 Phone NGN 150.00 Demo NGN 150.00
Standard	NIN, phone, demographic	NIN NGN 150.00 Phone NGN 150.00 Demo NGN 150.00
Premium	NIN, phone, demographic	NIN NGN 180.00 Phone NGN 200.00 Demo NGN 250.00
Basic	NIN only	NGN 150.00

BVN Verify V1

Slip	`slip_type`	Price
Standard	`standard`	NGN 150.00
Premium	`premium`	NGN 200.00

Endpoints

Method	Route	Purpose
GET	`v1/services`	List services and prices.
GET	`v1/balance`	Read wallet balance.
POST	`v1/nin/verify`	NIN slips; NIN, phone, or demographic search.
POST	`v1/bvn/verify`	BVN standard or premium slip.
POST	`v1/ipe/clearance`	Submit an IPE clearance.
GET	`v1/ipe/status`	Poll an owned IPE tracking ID.
POST / GET	`v1/nin/validation`	Submit a validation request / check its result.

NIN Verify V1

slip_type may be regular, standard, premium, or basic. The first three support nin, phone, and demographic methods. Basic supports NIN lookup only.

curl -X POST 'https://hadiverify.com.ng/api.php?route=v1/nin/verify' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"nin":"YOUR_11_DIGIT_NIN","slip_type":"premium","method":"nin"}'

Phone lookup

curl -X POST 'https://hadiverify.com.ng/api.php?route=v1/nin/verify' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"slip_type":"standard","method":"phone","phone":"YOUR_REGISTERED_PHONE"}'

Demographic lookup

curl -X POST 'https://hadiverify.com.ng/api.php?route=v1/nin/verify' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"slip_type":"regular","method":"demographic","firstname":"FIRST_NAME","lastname":"LAST_NAME","gender":"male","dob":"1990-01-01"}'

BVN Verify V1

slip_type may be standard or premium; it defaults to premium.

curl -X POST 'https://hadiverify.com.ng/api.php?route=v1/bvn/verify' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"bvn":"YOUR_11_DIGIT_BVN","slip_type":"standard"}'

IPE clearance

Use the provider-approved service_type. A successful submission returns HTTP 202 and status: pending.

curl -X POST 'https://hadiverify.com.ng/api.php?route=v1/ipe/clearance' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"tracking_id":"YOUR_15_CHARACTER_TRACKING_ID","service_type":"YOUR_PROVIDER_SERVICE_TYPE"}'

Check IPE status

curl -G 'https://hadiverify.com.ng/api.php' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --data-urlencode 'route=v1/ipe/status' \
  --data-urlencode 'tracking_id=YOUR_15_CHARACTER_TRACKING_ID'

NIN validation

Supported types: No Record Found, General validation, Photographic Error, Bank Validation, SIM Validation, and Modification Validation.

curl -X POST 'https://hadiverify.com.ng/api.php?route=v1/nin/validation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"nin":"YOUR_11_DIGIT_NIN","validation_type":"General validation"}'

Use the validation_id from the response to check status:

curl -G 'https://hadiverify.com.ng/api.php' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --data-urlencode 'route=v1/nin/validation' \
  --data-urlencode 'id=YOUR_VALIDATION_ID'

The current validation service queues requests for manual/provider processing. It does not return an automatic real-time verification result.

PHP integration

Run this from your server. Set HADI_VERIFY_API_KEY in the server environment and provide an authorized NIN through NIN_TO_VERIFY.

<?php
$apiUrl = 'https://hadiverify.com.ng/api.php';
$apiKey = getenv('HADI_VERIFY_API_KEY');
$nin = getenv('NIN_TO_VERIFY');

if (!$apiKey || !preg_match('/^[0-9]{11}$/', (string)$nin)) {
    throw new RuntimeException('Configure an API key and authorized 11-digit NIN.');
}

$curl = curl_init($apiUrl . '?route=v1/nin/verify');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        'nin' => $nin,
        'slip_type' => 'regular'
    ]),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Accept: application/json'
    ],
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT => 60
]);

$body = curl_exec($curl);
if ($body === false) {
    $error = curl_error($curl);
    curl_close($curl);
    throw new RuntimeException('API connection failed: ' . $error);
}
$httpStatus = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$result = json_decode($body, true);

header('Content-Type: application/json');
http_response_code($httpStatus);
echo json_encode($result);

Billing and responses

Successful NIN/BVN verifications are charged at the configured price. Failed requests are refunded. Successful verification responses include a first-party slip link that expires after seven days. Accepted IPE and validation requests are charged and may remain pending. Check both the HTTP status and JSON status field.

HTTP	Meaning
200	Completed successfully.
202	Accepted and pending.
400 / 422	Malformed JSON or invalid input.
401	Missing, invalid, or revoked API key.
402	Insufficient wallet balance.
502 / 503	Provider failure or missing server configuration.

Keep your Hadi Verify API key on your server. Never place it in public frontend code.