API Reference

Veripine API Documentation

Integrate real-time NIN & BVN verification for KYC and customer onboarding. Authenticate with an API key, send JSON, and get structured results — billed per request from your wallet.

REST · JSONx-api-key authconsent requiredwallet billing
Try the live sandbox Get your API key

API Pricing

Pay-as-you-go from your wallet. Prices shown are starting rates.
BVN Verification
₦145.00
Verify BVN number
NIN Demography Search
₦240.00
Search NIN using demographic data
NIN Phone Search
₦240.00
Search NIN using phone number
NIN Search
₦145.00
Search NIN using NIN number

Overview

The Veripine API is a RESTful service for verifying Nigerian identity records. Verify NIN and BVN by number, phone, tracking ID, or demographics, and receive clean JSON responses you can drop straight into your KYC or onboarding flow.

All verification requests require consent. You must include "consent": true in the request body, or the API responds with a 400 error.

API Sandbox — Try it live

Test every endpoint from your browser — no code required. The sandbox calls the live API and shows real responses, so what works there works in your code. Use Test my key to validate your API key for free before integrating.

Open the API Sandbox →

Authentication

Authenticate every request with your API key, using either header below.

Method 1 — x-api-key

x-api-key: YOUR_API_KEY

Method 2 — Authorization Bearer

Authorization: Bearer YOUR_API_KEY
Get your key: register an account, sign in, open API Settings, generate a key, and fund your wallet.

Base URL

All requests are made to:

https://veripine.com/api

Request Format

Send requests as POST with Content-Type: application/json (GET endpoints take query strings).

Required headers

Content-Type: application/json
x-api-key: YOUR_API_KEY

Body structure

{
    "nin": "12345678901",
    "consent": true
}

Response Format

All responses are JSON.

Success

{
    "status": "success",
    "reportID": "NIN_251021154942_59E172",
    "message": "ID Verified Successfully",
    "data": {
        "firstname": "JOHN",
        "surname": "ADEBAYO",
        "gender": "MALE",
        "nin": "12345678901",
        "birthdate": "1990-05-15"
    }
}

Error

{
    "status": "error",
    "message": "Invalid NIN format. NIN must be exactly 11 digits",
    "code": 400
}

Integration Examples

A real NIN verification call in four languages. Swap in your key and go.

curl -X POST https://veripine.com/api/nin-verification \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"nin":"12345678901","consent":true}'
$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "https://veripine.com/api/nin-verification",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => json_encode([
        "nin" => "12345678901",
        "consent" => true
    ]),
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "x-api-key: YOUR_API_KEY"
    ],
]);
$response = json_decode(curl_exec($curl), true);
curl_close($curl);
const res = await fetch("https://veripine.com/api/nin-verification", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
  },
  body: JSON.stringify({ nin: "12345678901", consent: true })
});
const data = await res.json();
import requests

res = requests.post(
    "https://veripine.com/api/nin-verification",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"nin": "12345678901", "consent": True},
    timeout=30,
)
print(res.json())

Endpoints

Every endpoint can be tested live in the sandbox.

EndpointMethodDescriptionFrom
/api/nin-verification POST NIN Verification from ₦150
/api/nin-phone POST NIN Phone Search from ₦200
/api/nin-tracking POST NIN Tracking from ₦200
/api/nin-demography POST NIN Demography Search from ₦250
/api/bvn-verification POST BVN Verification from ₦100
/api/bvn-phone POST BVN Phone Search from ₦150
/api/balance GET Account Balance Free
/api/nin-modification POST NIN Modification Orders from ₦6,000
/api/nin-modification-status GET Modification Order Status Free
POST

NIN Verification

from ₦150

Verify a National Identity Number (NIN) and retrieve the associated record.

POSThttps://veripine.com/api/nin-verification

Request body

{
    "nin": "12345678901",
    "consent": true
}

Example request

curl -X POST https://veripine.com/api/nin-verification \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"nin":"12345678901","consent":true}'

Example response

{
    "status": "success",
    "reportID": "NIN_251021154942_59E172",
    "message": "NIN Verified Successfully",
    "data": {
        "firstname": "JOHN",
        "middlename": "OLUMIDE",
        "surname": "ADEBAYO",
        "telephoneno": "08012345678",
        "gender": "MALE",
        "nin": "12345678901",
        "birthdate": "1990-05-15",
        "residence_state": "LAGOS",
        "photo": "data:image/jpeg;base64,..."
    }
}

Try NIN Verification in the sandbox →

POST

NIN Phone Search

from ₦200

Search for a NIN record using a phone number.

POSThttps://veripine.com/api/nin-phone

Request body

{
    "phone": "08012345678",
    "consent": true
}

Example request

curl -X POST https://veripine.com/api/nin-phone \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"phone":"08012345678","consent":true}'

Example response

{
    "status": "success",
    "message": "NIN Retrieved Successfully",
    "data": {
        "nin": "12345678901",
        "firstname": "JOHN",
        "surname": "ADEBAYO"
    }
}

Try NIN Phone Search in the sandbox →

POST

NIN Tracking

from ₦200

Search for a NIN record using a tracking ID.

POSThttps://veripine.com/api/nin-tracking

Request body

{
    "tracking_id": "7Y0OG2ZO003KUPG",
    "consent": true
}

Example request

curl -X POST https://veripine.com/api/nin-tracking \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"tracking_id":"7Y0OG2ZO003KUPG","consent":true}'

Example response

{
    "status": "success",
    "message": "NIN Retrieved Successfully",
    "data": {
        "nin": "12345678901",
        "firstname": "JOHN",
        "surname": "ADEBAYO"
    }
}

Try NIN Tracking in the sandbox →

POST

NIN Demography Search

from ₦250

Search for a NIN record using demographic data.

POSThttps://veripine.com/api/nin-demography

Request body

{
    "firstname": "JOHN",
    "lastname": "ADEBAYO",
    "gender": "male",
    "dob": "1990-05-15",
    "consent": true
}

Example request

curl -X POST https://veripine.com/api/nin-demography \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"firstname":"JOHN","lastname":"ADEBAYO","gender":"male","dob":"1990-05-15","consent":true}'

Example response

{
    "status": "success",
    "message": "Match Found",
    "data": {
        "nin": "12345678901",
        "firstname": "JOHN",
        "surname": "ADEBAYO"
    }
}

Try NIN Demography Search in the sandbox →

POST

BVN Verification

from ₦100

Verify a Bank Verification Number (BVN) and retrieve the associated record.

POSThttps://veripine.com/api/bvn-verification

Request body

{
    "bvn": "22350591353",
    "consent": true
}

Example request

curl -X POST https://veripine.com/api/bvn-verification \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"bvn":"22350591353","consent":true}'

Example response

{
    "status": "success",
    "reportID": "BVN_251019185403_3A7269",
    "message": "BVN Verified Successfully",
    "data": {
        "firstname": "JOHN",
        "middlename": "OLUMIDE",
        "lastname": "ADEBAYO",
        "phone": "08012345678",
        "bvn": "22350591353",
        "dob": "15-May-90",
        "gender": "Male",
        "state_of_residence": "Lagos",
        "nationality": "Nigerian",
        "photo": "data:image/jpeg;base64,..."
    }
}

Try BVN Verification in the sandbox →

POST

BVN Phone Search

from ₦150

Search for a BVN record using a phone number.

POSThttps://veripine.com/api/bvn-phone

Request body

{
    "phone": "08012345678",
    "consent": true
}

Example request

curl -X POST https://veripine.com/api/bvn-phone \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"phone":"08012345678","consent":true}'

Example response

{
    "status": "success",
    "message": "BVN Retrieved Successfully",
    "data": {
        "bvn": "22350591353",
        "firstname": "JOHN",
        "lastname": "ADEBAYO"
    }
}

Try BVN Phone Search in the sandbox →

GET

Account Balance

Free

Check your wallet balance and API usage. This endpoint is free to call.

GEThttps://veripine.com/api/balance

Example request

curl -X GET "https://veripine.com/api/balance" \
  -H "x-api-key: YOUR_API_KEY"

Example response

{
    "status": "success",
    "message": "Balance retrieved successfully",
    "data": {
        "balance": 5000,
        "formatted_balance": "₦5,000.00",
        "user_type": "regular",
        "api_requests_today": 25,
        "api_limit": 1000
    }
}

Try Account Balance in the sandbox →

POST

NIN Modification Orders

from ₦6,000

Submit a NIN modification or validation order. Orders are reviewed within 24–48 hours and your wallet is charged on submission.

POSThttps://veripine.com/api/nin-modification

Request body

{
    "service_type": "nin_name_modification",
    "nin": "12345678901",
    "surname": "ADEBAYO",
    "firstname": "JOHN",
    "phone_number": "08012345678",
    "new_surname": "ADEBAYO",
    "new_firstname": "JOHNSON",
    "consent": true
}

Example request

curl -X POST https://veripine.com/api/nin-modification \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"service_type":"nin_name_modification","nin":"12345678901","surname":"ADEBAYO","firstname":"JOHN","phone_number":"08012345678","new_surname":"ADEBAYO","new_firstname":"JOHNSON","consent":true}'

Example response

{
    "status": "success",
    "reportID": "NM_API_251021154942_59E172",
    "message": "NIN Name Modification order submitted successfully",
    "data": {
        "order_id": 45,
        "reference_id": "NM_API_251021154942_59E172",
        "service_type": "nin_name_modification",
        "amount_charged": 16000,
        "status": "pending"
    }
}
Service types: nin_name_modification, nin_phone_modification, nin_address_modification (₦16,000) and nin_validation (₦6,000). Rejected orders are automatically refunded.

Try NIN Modification Orders in the sandbox →

GET

Modification Order Status

Free

Check the processing status of a modification order using its reference_id. Available as GET (query string) or POST (JSON body).

GEThttps://veripine.com/api/nin-modification-status?reference_id=NM_API_251021154942_59E172

Example request

curl -X GET "https://veripine.com/api/nin-modification-status?reference_id=NM_API_251021154942_59E172" \
  -H "x-api-key: YOUR_API_KEY"

Example response

{
    "status": "success",
    "message": "Order status retrieved successfully",
    "data": {
        "order_id": 45,
        "reference_id": "NM_API_251021154942_59E172",
        "status": "completed",
        "status_detail": "Your order has been successfully completed."
    }
}

Try Modification Order Status in the sandbox →

Error Codes

CodeMeaningDescription
200OKRequest successful
400Bad RequestInvalid format or missing fields (including missing consent)
401UnauthorizedInvalid or missing API key
403ForbiddenAPI access disabled or insufficient permissions
405Method Not AllowedHTTP method not supported for this endpoint
429Too Many RequestsDaily request limit exceeded
500Server ErrorAn error occurred on the server
503UnavailableService temporarily unavailable

Common errors

{
    "status": "error",
    "message": "Consent is required. Please include \"consent\": true in your request",
    "code": 400
}
{
    "status": "error",
    "message": "Insufficient wallet balance",
    "code": 400
}

Support

Stuck on an integration? The fastest fix is usually the sandbox — validate your key, reproduce your request, and copy working code. For anything else, reach out from your dashboard.

Create an account to get started →