Overview

The AmbVerify API gives you programmatic access to our identity verification services. Submit NIN validation or IPE clearance requests in bulk, check statuses, and manage your wallet — all via simple REST endpoints.

All requests and responses use JSON. Amounts are in Nigerian Naira (NGN).

Authentication

All endpoints (except Health Check) require a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Your API key is a 64-character string provided by the AmbVerify admin team. Keep it secret — treat it like a password. If compromised, contact support to regenerate it.

Requests without a valid key receive a 401 response.

Base URL

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

Error Handling

All errors return a consistent JSON structure:

{
  "success": false,
  "error": "Description of what went wrong"
}
HTTP CodeMeaning
400Bad request — missing or invalid parameters
401Unauthorized — missing or invalid API key
402Insufficient wallet balance
405Method not allowed
422Validation error — correct the input and retry
500Server error — contact support if persistent
503Pricing not configured — contact support

NIN Validation

Submit one or more NINs for manual validation. Wallet is charged immediately.

POST /api/v1/nin_validation.php
Request Body
FieldTypeDescription
nins required array of strings NINs to validate (each must be exactly 11 digits). Max 100 per request.
validation_type required string One of: No Record Found, Photographic error, Modification validation, Bank validation, SIM validation
Example Request
curl -X POST https://ambverify.com.ng/api/v1/nin_validation.php \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nins": ["12345678901", "98765432101"],
    "validation_type": "No Record Found"
  }'
Success Response 201
{
  "success": true,
  "batch_id": "A3F8C901",
  "api_request_id": 42,
  "items_submitted": 2,
  "total_charged": 1000.00,
  "wallet_balance": 9000.00,
  "items": [
    { "nin": "12345678901", "status": "New", "id": 101 },
    { "nin": "98765432101", "status": "New", "id": 102 }
  ]
}

Note: Invalid NINs (not 11 digits) are silently skipped. If any are skipped, the response includes a skipped array and a note field.

IPE Clearance

Submit tracking IDs for IPE clearance processing. Results are delivered asynchronously via webhooks.

POST /api/v1/ipe_clearance.php
Request Body
FieldTypeDescription
tracking_ids required array of strings IPE tracking IDs to process. Max 100 per request.
Example Request
curl -X POST https://ambverify.com.ng/api/v1/ipe_clearance.php \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_ids": ["TID-001", "TID-002"]
  }'
Success Response 201
{
  "success": true,
  "batch_id": "B7E2D4F1",
  "api_request_id": 43,
  "items_submitted": 2,
  "total_charged": 500.00,
  "wallet_balance": 8500.00,
  "items": [
    { "tracking_id": "TID-001", "status": "pending", "id": 201 },
    { "tracking_id": "TID-002", "status": "pending", "id": 202 }
  ]
}

Check Status

Query the status of your submitted requests. Provide at least one filter parameter.

GET /api/v1/check_status.php
Query Parameters
ParameterTypeDescription
batch_id optional string Filter by batch ID (returned when you submit a request)
api_request_id optional integer Filter by the API request ID
tracking_id optional string Look up a specific IPE tracking ID
nin optional string Look up a specific NIN (11 digits)
Example Request
curl -X GET "https://ambverify.com.ng/api/v1/check_status.php?batch_id=A3F8C901" \
  -H "Authorization: Bearer YOUR_API_KEY"
Success Response 200
{
  "success": true,
  "count": 2,
  "items": [
    {
      "service": "nin_validation",
      "id": 101,
      "nin": "12345678901",
      "validation_type": "No Record Found",
      "status": "Completed",
      "reply": "Validation result details...",
      "amount": 500.00,
      "created_at": "2026-03-28 10:30:00",
      "updated_at": "2026-03-28 14:15:00"
    }
  ]
}

Wallet Balance

Check your current wallet balance and virtual account details for funding.

GET /api/v1/wallet.php
Example Request
curl -X GET https://ambverify.com.ng/api/v1/wallet.php \
  -H "Authorization: Bearer YOUR_API_KEY"
Success Response 200
{
  "success": true,
  "wallet_balance": 9500.00,
  "currency": "NGN",
  "virtual_account": {
    "account_number": "1234567890",
    "account_name": "AmbVerify / YourCompany",
    "bank_name": "Wema Bank"
  }
}

Fund your wallet by transferring to the virtual account shown. Balance updates automatically via webhook.

Prices

Get current pricing for all API services. Custom pricing (if configured for your account) is reflected automatically.

GET /api/v1/prices.php
Example Request
curl -X GET https://ambverify.com.ng/api/v1/prices.php \
  -H "Authorization: Bearer YOUR_API_KEY"
Success Response 200
{
  "success": true,
  "currency": "NGN",
  "services": {
    "ipe_clearance": {
      "price_per_item": 250.00
    },
    "nin_validation": {
      "types": [
        { "validation_type": "No Record Found", "price": 500.00 },
        { "validation_type": "Photographic error", "price": 500.00 },
        { "validation_type": "Modification validation", "price": 500.00 },
        { "validation_type": "Bank validation", "price": 500.00 },
        { "validation_type": "SIM validation", "price": 500.00 }
      ]
    }
  }
}

Health Check

Public endpoint — no authentication required. Use this to verify the API is online.

GET /api/v1/status.php
Example Request
curl -X GET https://ambverify.com.ng/api/v1/status.php
Response 200
{
  "status": "ok",
  "version": "1.0",
  "service": "AmbVerify API"
}

Webhook Events

When the status of your request is updated (e.g., IPE clearance completed, NIN validated), we send a POST request to your configured webhook URL.

POST Your webhook URL
Headers Sent
HeaderDescription
Content-Typeapplication/json
X-AmbVerify-SignatureHMAC-SHA256 hex digest of the request body
X-AmbVerify-EventEvent type (currently status_update)
Payload Example (IPE Clearance)
{
  "event": "status_update",
  "service": "ipe_clearance",
  "tracking_id": "TID-001",
  "request_id": 201,
  "api_request_id": 43,
  "status": "completed",
  "reply": "Clearance result details...",
  "timestamp": "2026-03-28T14:15:00Z"
}
Payload Example (NIN Validation)
{
  "event": "status_update",
  "service": "nin_validation",
  "nin": "12345678901",
  "request_id": 101,
  "api_request_id": 42,
  "status": "Completed",
  "reply": "Validation result details...",
  "timestamp": "2026-03-28T14:15:00Z"
}
Retry Policy

If your server doesn't respond with a 2xx status code, we retry up to 5 times with exponential backoff:

  • Retry 1: after 5 minutes
  • Retry 2: after 15 minutes
  • Retry 3: after 1 hour
  • Retry 4: after 6 hours
  • Retry 5: after 24 hours

Signature Verification

Always verify the X-AmbVerify-Signature header to confirm the webhook came from AmbVerify.

PHP Example
$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_AMBVERIFY_SIGNATURE'] ?? '';
$expected  = hash_hmac('sha256', $payload, 'YOUR_WEBHOOK_SECRET');

if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit('Invalid signature');
}

$data = json_decode($payload, true);
// Process the webhook...
Node.js Example
const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signature)
  );
}
Python Example
import hmac, hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Rate Limits

Current limits per API client:

If you need higher limits, contact our support team.

Support

Need help getting started, or have questions about the API?

ambverify.com.ng support@ambverify.com.ng