ID Verification
Verify a NIN or BVN against the source register and return the holder's record — with all the NIN lookup modes and BVN tiers Truztcube supports.
ID verification confirms a government identity number and returns the holder's record from the source register. Truztcube supports NIN (via NIMC) and BVN (via the banking register).
NIN verification
Several lookup modes, each a POST under /v1/nin:
| Mode | Endpoint | Body |
|---|---|---|
| Raw lookup | /v1/nin/raw/lookup | nin, enterpriseId (required), requestReason |
| ShareCode | /v1/nin/sharecode/lookup | shareCode (required), enterpriseId (required), requestReason |
| Phone → NIN | /v1/nin/phone/lookup | phone number, enterpriseId (required), reason |
| Face match | /v1/nin/face-match/lookup | nin, enterpriseId (required), requestReason, selfieImage, livelinessImages — see Biometrics |
curl -X POST https://api.truztcube.com/v1/nin/raw/lookup \
-H "x-api-key: sk_test_your_key" \
-H "Content-Type: application/json" \
-d '{ "nin": "00000000000", "enterpriseId": "ENT...", "requestReason": "KYC" }'requestReason records the lawful purpose of the check. Fetch the permitted values from
GET /v1/nin/request-reasons.
enterpriseId is required, and it selects the data tier your lookup is served under.
Send the enterprise credential issued to your organisation
enterpriseId names the NIMC enterprise credential your request is routed under, and the
credential — not the endpoint — determines how much of the holder's record comes back.
Send only a credential issued to your organisation: the tier is a property of the credential at NIMC, so naming one you do not hold is a contractual and data-protection breach on your side, and usage is reconciled against NIMC's per-key records and billed at the tier actually served.
BVN verification
BVN comes in tiers, each a POST under /v1/bvn. All accept a consent assertion
(consentGranted, consentReference) since the data subject must consent to a BVN check.
| Tier | Endpoint | Returns |
|---|---|---|
| Basic | /v1/bvn/basic | Core record for the BVN |
| Advance | /v1/bvn/advance | Fuller record |
| Face validation | /v1/bvn/face-validation | Record + face match (image) |
curl -X POST https://api.truztcube.com/v1/bvn/basic \
-H "x-api-key: sk_test_your_key" \
-H "Content-Type: application/json" \
-d '{
"number": "00000000000",
"consentGranted": true,
"consentReference": "your-consent-ref"
}'Consent
You assert consent per request; Truztcube records the assertion. Ensure you hold a valid lawful basis for every BVN check — see Security.
Response
Every ID verification returns the standard envelope: a status, a Truztcube verification ID, and the verified fields your access level permits. Empty register fields are omitted rather than null-filled. Exact per-endpoint schemas are in the API Reference.
Access levels & pricing
The fields returned and the per-verification cost depend on your access level. See Pricing.
Related
- Biometric Authentication — face match / validation.
- Errors & Statuses — how to branch on the outcome.
- API Reference — full NIN & BVN contracts.
Authentication
How Truztcube authenticates requests — API keys (x-api-key) for the verification API, and JWT for the dashboard — plus how to generate, scope, and revoke keys.
Biometric Authentication
Face-match a live capture against the identity on record — via NIN face-match or BVN face-validation — for step-up identity assurance.