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.

number*string

BVN number (exactly 11 numeric digits).

Length11 <= length <= 11

consentGranted*boolean

Explicit consent from the data subject to retrieve their BVN data. Must be true.

consentReference*string

Reference identifying where and how consent was obtained (e.g. log identifier, session ID).

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