Verification — overview

RandaVerify exposes five forward verification modes plus an idempotent re-query. Every mode returns the same normalised response shape so you can switch between them based on what data your customer can give you, without re-mapping fields.

Decision matrix

You have…	Use
11-digit NIN	Standard
11-digit NIN and a fresh selfie of the holder	In-Person
6-character share code generated in the NIMC mobile app	Share Code
11-digit Nigerian phone number	Phone
First name + last name + DOB + gender (no NIN)	Demography
A `reference_id` from a past verification	Re-query (no charge)

What every verification has in common

Endpoint base: https://api.randaverify.com/verify-nin[/…]
Method: POST (JSON body) — except re-query which is also POST.
Auth: Authorization: Bearer <token> (see Authentication).
Reason: every forward request requires a reason field whose value is a key from GET /nimc-reasons. Demography is the exception — it accepts only nyscCheck.
Cost: 1 unit per successful verification, debited from your org wallet. Failed requests are not charged. Re-queries are not charged.
Response envelope: success bodies are wrapped in { "data": { … } }.

Response shape (success)

{
  "data": {
    "transaction_id": "430542871707201461583",
    "reference_id": "REF-1A2B3C4D5E6F",
    "nin": "12345678901",
    "tracking_id": "...",
    "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 shape

{ "detail": "Insufficient units in organisation wallet" }

See Error reference for the full table.