Standard (NIN)

The default verification path. Provide an 11-digit NIN and a reason; receive the holder’s record.

POST/verify-nin

Request

Field	Type	Required	Notes
nin	string	✅	Exactly 11 digits
reason	string	✅	A key from /nimc-reasons

curl

curl -X POST https://api.randaverify.com/verify-nin \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nin": "12345678901",
    "reason": "corporate"
  }'

Python

import requests

resp = requests.post(
    "https://api.randaverify.com/verify-nin",
    headers={"Authorization": f"Bearer {token}"},
    json={"nin": "12345678901", "reason": "corporate"},
    timeout=30,
)
resp.raise_for_status()
data = resp.json()["data"]
print(data["fname"], data["lname"], data["reference_id"])

Node

const res = await fetch('https://api.randaverify.com/verify-nin', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ nin: '12345678901', reason: 'corporate' }),
});
if (!res.ok) throw new Error(`Verification failed: ${res.status}`);
const { data } = await res.json();
console.log(data.fname, data.lname, data.reference_id);

Response (200)

The standard NIN verification populates the full record shape — every field documented in Conventions → field-name casing will be present (some may legitimately be empty strings if NIMC has no value).

{
  "data": {
    "transaction_id": "430542871707201461583",
    "reference_id": "REF-1A2B3C4D5E6F",
    "nin": "12345678901",
    "tracking_id": "1234567890123",
    "fname": "JANE",
    "mname": "M",
    "lname": "DOE",
    "dob": "01-01-1990",
    "phone": "08012345678",
    "gender": "Female",
    "residenceAdress": "1 Test Road",
    "residenceTown": "Ikeja",
    "residenceLga": "Ikeja",
    "residenceState": "Lagos",
    "stateOfOrigin": "Lagos",
    "lgaOfOrigin": "Lagos Mainland",
    "maidenName": "not found",
    "image": "<base64 jpeg>"
  }
}

Failure modes

Status	When	Recover by
400	NIN failed validation, or upstream NIMC rejected the request (invalid reason, etc.)	Inspect detail. Likely a malformed NIN or an unsupported reason value.
402	Org wallet has no units	Top up the wallet before retrying.
500	Upstream NIMC is unreachable	Retry with backoff. If persistent, contact support with the reference_id.

Idempotency

A successful call inserts a NIN_VALIDATION transaction row tied to the user, org, and a fresh reference_id. To replay the same lookup without burning another unit, store the reference_id and call /verify-nin/requery later.