Verification reasons

NIMC’s verification engine rejects any request whose reason is not on its current allow-list. RandaVerify fetches that list from NIMC for you and exposes it via a single endpoint.

GET/nimc-reasons

Why you should fetch this list at runtime

• The set of valid reasons changes — NIMC adds/removes from time to time without versioning.
• Different verification modes accept different subsets (see below).
• Hard-coding a reason that NIMC later removes will break your integration.

The supported pattern: fetch the list once per session (or once per day) and cache it client-side. Refresh when you see a 400 Invalid requestReason provided from NIMC.

Request

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

Response

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

You pass the key (camelCase) — not the label — as the reason field on a verification call.

Endpoint-specific constraints

Some endpoints accept only a narrower subset of reasons. Always honour these caps regardless of what /nimc-reasons returns:

Endpoint	Accepted reasons
/verify-nin	Any key returned by /nimc-reasons
/verify-nin/in-person	Any key returned by /nimc-reasons
/verify-nin/share-code	Any key returned by /nimc-reasons
/verify-nin/phone	Any key returned by /nimc-reasons
/verify-nin/demography	nyscCheck only
/verify-nin/requery	n/a (no reason needed)

Caution

Passing the human-readable label (e.g. "Corporate") instead of the key (e.g. "corporate") is the most common cause of 400 Invalid requestReason provided errors. Always pass key.