BVN Verification

Verify an identity using an 11-digit BVN.

Verify an identity record using an 11-digit BVN.

POST /v1/verifications/bvn

PropertyValue
ScopeBVN_VERIFY
Live price₦110
Test charge₦0
Idempotency-KeyRequired
⚠️

Check data.status

SUCCESSFUL, NOT_FOUND, and BLOCKED are completed outcomes. They all return HTTP 200 and live requests are charged.

Headers

Authorization: Bearer id_test_your_key
Idempotency-Key: req_550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

Request body

FieldTypeRequiredDescription
bvnstringYesExactly 11 digits.
{
  "bvn": "22222222222"
}

cURL example

curl -X POST "https://api.idyntic.getapexly.com/v1/verifications/bvn" \
  -H "Authorization: Bearer id_test_your_key" \
  -H "Idempotency-Key: req_550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"bvn":"22222222222"}'

HTTP 200: successful verification

The object inside bvn_data contains the complete verification data for this endpoint. Empty strings and null values are intentionally preserved.

{
  "success": true,
  "message": "BVN Verification (BVN) Successful",
  "data": {
    "reference": "550e8400-e29b-41d4-a716-446655440001",
    "status": "SUCCESSFUL",
    "type": "bvn",
    "environment": "live",
    "bvn_data": {
      "bvn": "22222222222",
      "firstName": "CHIDINMA",
      "middleName": "ADAEZE",
      "lastName": "NWACHUKWU",
      "dateOfBirth": "05-Dec-1994",
      "phoneNumber1": "08012345678",
      "phoneNumber2": "",
      "gender": "Female",
      "residentialAddress": "24 SPECIMEN AVENUE, OFF DEMO ROAD",
      "stateOfOrigin": "Lagos State",
      "lgaOfOrigin": "Ikeja",
      "stateOfResidence": "",
      "lgaOfResidence": "Ikeja",
      "nationality": "Nigeria",
      "title": "",
      "nameOnCard": "",
      "watchListed": "False",
      "maritalStatus": "Single",
      "registrationDate": "05-Dec-2014",
      "enrollmentBank": "",
      "enrollmentBranch": "",
      "levelOfAccount": "",
      "watchListMessage": "",
      "nin": "",
      "email": "",
      "base64Image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2Q=="
    }
  },
  "billing": {
    "amount": 110,
    "currency": "NGN",
    "unit": "naira",
    "charged": true,
    "note": "Wallet charged 110.00 NGN"
  }
}

The sample photo value is a shortened dummy JPEG Base64 value. Live responses contain the complete Base64-encoded image.

HTTP 200: record not found

{
  "success": true,
  "message": "Record not found",
  "data": {
    "reference": "550e8400-e29b-41d4-a716-446655440002",
    "status": "NOT_FOUND",
    "type": "bvn",
    "environment": "live",
    "bvn_data": null
  },
  "billing": {
    "amount": 110,
    "currency": "NGN",
    "unit": "naira",
    "charged": true,
    "note": "Wallet charged 110.00 NGN"
  }
}

HTTP 200: BVN blocked or watchlisted

{
  "success": true,
  "message": "This BVN is blocked or watchlisted.",
  "data": {
    "reference": "550e8400-e29b-41d4-a716-446655440003",
    "status": "BLOCKED",
    "type": "bvn",
    "environment": "live",
    "bvn_data": null
  },
  "billing": {
    "amount": 110,
    "currency": "NGN",
    "unit": "naira",
    "charged": true,
    "note": "Wallet charged 110.00 NGN"
  }
}

A restricted outcome may include verification data. When it is unavailable, bvn_data is null.

Error responses

HTTPCodeWhen it happens
400INVALID_REQUESTBVN must be 11 digits
400INVALID_IDEMPOTENCY_KEYHeader is missing or does not match the required format
401UNAUTHORIZEDKey is invalid, expired, revoked, or lacks BVN_VERIFY
402INSUFFICIENT_BALANCELive wallet balance is below ₦110
409IDEMPOTENCY_KEY_REUSEDThe key was used with a different request body
409IDEMPOTENCY_IN_PROGRESSThe same live operation is still processing
429RATE_LIMIT_EXCEEDEDPer-key request limit was exceeded
500INTERNAL_ERRORAn unexpected error prevented completion
503SERVICE_UNAVAILABLEThe verification service is temporarily unavailable

Invalid request example

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "BVN must be 11 digits",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "billing": {
    "amount": 110,
    "currency": "NGN",
    "unit": "naira",
    "charged": false,
    "note": "No charges"
  }
}

Insufficient balance example

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your wallet balance is insufficient for this verification.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "billing": {
    "amount": 110,
    "currency": "NGN",
    "unit": "naira",
    "charged": false,
    "note": "No charges"
  }
}

Idempotency conflict example

{
  "success": false,
  "error": {
    "code": "IDEMPOTENCY_KEY_REUSED",
    "message": "This Idempotency-Key was already used with a different request.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "billing": {
    "amount": 110,
    "currency": "NGN",
    "unit": "naira",
    "charged": false,
    "note": "No charges"
  }
}

Service unavailable example

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Verification service is temporarily unavailable, try again later.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "billing": {
    "amount": 110,
    "currency": "NGN",
    "unit": "naira",
    "charged": false,
    "note": "No charges"
  }
}

All error responses have charged: false. See Errors for retry guidance.