Conventions

This page collects the cross-cutting rules every endpoint follows. Skim it once so the rest of the docs feel familiar.

Content types

• Verification endpoints accept and return application/json.
• POST /login accepts application/x-www-form-urlencoded (OAuth2 password flow). Every other endpoint is JSON.
• Responses always include a Content-Type: application/json; charset=utf-8 header.

Status codes

Code	Meaning
200	The request succeeded. The body contains a data envelope for verification calls, or a top-level resource for other calls.
400	Validation failed — your request body is missing a required field or contains an invalid value. The detail field names the problem.
401	Token is missing, expired, or invalid. Re-authenticate.
402	Insufficient units. Top up your wallet before retrying.
403	Token is valid, but the user lacks permission for this action.
404	The referenced resource does not exist. Most common on /verify-nin/requery with an unknown reference_id.
422	Pydantic validation error — typically a malformed payload (wrong type, missing field).
429	Rate-limited — slow down and retry with backoff.
5xx	RandaVerify is having a bad day. Retry with exponential backoff; if it persists, contact support with your reference_id.

The error body shape is consistent:

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

Field-name casing

Verification responses use camelCase for NIMC-sourced fields (e.g. dateOfBirth, firstname, residenceAddressLine1) but RandaVerify normalises them to a consistent snake-friendly schema before returning. You always receive:

Field	Source aliases
nin	nin, NIN, identityNumber
fname	firstname, firstName, fname
mname	middlename, middleName, mname
lname	surname, lastName, lname
dob	dateOfBirth, birthdate, dob
phone	telephoneno, mobile, phone, phone1
residenceAdress	residence_AdressLine1, address (note original NIMC mis-spelling preserved)
residenceTown	town, city
residenceLga	residence_lga, lga
residenceState	state
stateOfOrigin	self_origin_state, birthState
lgaOfOrigin	self_origin_lga, birthLga
image	photo, base64 JPEG

This way you do not need to know which key NIMC happened to use — RandaVerify returns the same shape every time.

Reference IDs

Every verification produces a reference_id of the form REF-XXXXXXXXXXXX. Persist it. You can:

• Look the record up again later with /verify-nin/requery (no unit charged).
• Quote it to support when reporting an issue.
• Use it as your idempotency key for retry-safe persistence on your side.

Phone numbers & dates

• Phone numbers are Nigerian 11-digit format beginning with 0 (e.g. 08012345678).
• Dates of birth are dd-mm-yyyy (e.g. 03-09-1999) on the demography request side. The dob returned in responses uses the same format.

Reasons

NIMC validates every verification against a fixed list of allowed reasons. Always fetch the current list from GET /nimc-reasons and pass the key (not the human label) in your request:

curl https://api.randaverify.com/nimc-reasons -H "Authorization: Bearer $TOKEN"

{
  "data": [
    { "key": "corporate", "label": "Corporate", "description": "..." },
    { "key": "nyscCheck", "label": "NYSC Check", "description": "..." },
    { "key": "telecommunicationSimReg", "label": "Telecom SIM Reg", "description": "..." }
  ]
}

Caution

Some endpoints accept only a subset of reasons. In particular, /verify-nin/demography only accepts nyscCheck. See each endpoint page for endpoint-specific reason constraints.

Wallet semantics

• Every successful verification debits one unit from your org wallet.
• A failed verification does not debit your wallet (you only pay for results).
• A re-query does not debit your wallet (idempotent retrieval).
• You can check your current balance via GET /me → organisation (the unit count is available in admin contexts; for the standard officer flow, see your wallet via the portal).