Truztcube Docs
API ReferenceBVN Verification

BVN Basic Lookup

Verify a BVN number and retrieve basic identity data (name, date of birth, gender, phone). Requires a valid Idempotency-Key header for live-mode API keys to prevent duplicate charges.

POST/v1/bvn/basic

Authorization

api-key
x-api-key<token>

In: header

Header Parameters

X-Correlation-ID?string

Optional. Trace ID propagated to Prembly for end-to-end log correlation.

Idempotency-Key?string

Required for live-mode keys. Unique key identifying this request attempt.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/v1/bvn/basic" \  -H "Content-Type: application/json" \  -d '{    "number": "22222222222",    "consentGranted": true,    "consentReference": "CONSENT-REF-2024-001"  }'
{  "success": true,  "statusCode": 200,  "message": "Request processed successfully",  "timestamp": "2025-10-20T16:30:00.000Z",  "path": "/v1/auth/register",  "data": {    "verificationStatus": "VERIFIED",    "referenceId": {},    "verificationId": {},    "charged": true,    "chargeAmount": 0,    "verificationData": {      "firstName": {},      "lastName": {},      "middleName": {},      "dateOfBirth": {},      "phoneNumber1": {}    }  }}
Empty
Empty
Empty
Empty

Enhanced phone lookup

Resolve a phone number (MSISDN) to a NIN identity record via TruztFix resolution + NIMC lookup. Requires an active Enhanced Phone Lookup subscription. Primary path: TruztFix resolves MSISDN→NIN, then NIMC raw lookup. Fallback path: NIMC phone-number lookup when TruztFix cannot resolve the MSISDN.

BVN Advance Lookup

Verify a BVN and retrieve the full biographic record (address, state of origin, LGA, marital status, etc.). Requires a valid Idempotency-Key header for live-mode keys.