Demography

Use demography when the only data you have is the holder’s name, date of birth and gender.

POST/verify-nin/demography

Reason is fixed

NIMC’s demography endpoint accepts only nyscCheck as the reason value. Any other reason will be rejected with 400 Invalid requestReason provided. The RandaVerify backend hard-codes this for you on the in-portal form, but if you are calling the API directly you must pass "reason": "nyscCheck".

Request

Field	Type	Required	Notes
first_name	string	✅	Holder’s first name
last_name	string	✅	Holder’s last name
date_of_birth	string	✅	dd-mm-yyyy (e.g. 03-09-1999)
gender	string	✅	m or f
reason	string	✅	Must be nyscCheck

curl

curl -X POST https://api.randaverify.com/v1/verify-nin/demography \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Uchechi",
    "last_name": "Igwedinma",
    "date_of_birth": "22-10-1988",
    "gender": "f",
    "reason": "nyscCheck"
  }'

Python

resp = requests.post(
    "https://api.randaverify.com/v1/verify-nin/demography",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "first_name": "Uchechi",
        "last_name": "Igwedinma",
        "date_of_birth": "22-10-1988",
        "gender": "f",
        "reason": "nyscCheck",
    },
    timeout=30,
)

Node

const res = await fetch('https://api.randaverify.com/v1/verify-nin/demography', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    first_name: 'Uchechi',
    last_name: 'Igwedinma',
    date_of_birth: '22-10-1988',
    gender: 'f',
    reason: 'nyscCheck',
  }),
});
if (!res.ok) throw new Error(`Demography verification failed: ${res.status}`);
const { data } = await res.json();
console.log(data.fname, data.lname, data.reference_id);

Response (200)

Same shape as the standard NIN response. Returns the matched record (typically with full name, DOB, NIN where exposed, address line, origin state/LGA).

Failure modes

Status	When	Recover by
400	gender is not m/f; date_of_birth is not dd-mm-yyyy; reason is anything other than nyscCheck	Fix the input.
402	Org wallet empty	Top up.
404	NIMC has no record matching the demographic combo	The data may be slightly different in NIMC’s records, try variations or fall back to phone/NIN once available.