Find and verify a BVN record using a Nigerian phone number.
Verify an identity record using a Nigerian phone number.
POST /v1/verifications/bvn/phone
| Property | Value |
|---|---|
| Scope | BVN_VERIFY |
| Live price | ₦100 |
| Test charge | ₦0 |
| Idempotency-Key | Required |
Checkdata.status
SUCCESSFUL,NOT_FOUND, andBLOCKEDare completed outcomes. They all return HTTP200and live requests are charged.
Headers
Authorization: Bearer id_test_your_key
Idempotency-Key: req_550e8400-e29b-41d4-a716-446655440000
Content-Type: application/jsonRequest body
| Field | Type | Required | Description |
|---|---|---|---|
phone | string | Yes | A valid Nigerian number such as 08012345678 or +2348012345678. |
{
"phone": "08012345678"
}cURL example
curl -X POST "https://api.idyntic.getapexly.com/v1/verifications/bvn/phone" \
-H "Authorization: Bearer id_test_your_key" \
-H "Idempotency-Key: req_550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{"phone":"08012345678"}'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 (Phone) Successful",
"data": {
"reference": "550e8400-e29b-41d4-a716-446655440001",
"status": "SUCCESSFUL",
"type": "bvn_phone",
"environment": "live",
"bvn_data": {
"bvn": "22222222222",
"firstName": "CHIDINMA",
"middleName": "ADAEZE",
"lastName": "NWACHUKWU",
"dateOfBirth": "05-Dec-1994",
"phoneNumber1": "08012345678",
"phoneNumber2": "",
"email": "",
"gender": "Female",
"enrollmentBank": "Access Bank",
"enrollmentBranch": "Ikeja Main",
"lgaOfOrigin": "Ikeja",
"lgaOfResidence": "Ikeja",
"maritalStatus": "Single",
"nin": "",
"nameOnCard": "",
"nationality": "Nigeria",
"residentialAddress": "24 SPECIMEN AVENUE, OFF DEMO ROAD",
"stateOfOrigin": "Lagos State",
"stateOfResidence": "",
"title": "",
"watchListed": "False",
"levelOfAccount": "",
"registrationDate": "05-Dec-2014",
"base64Image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2Q==",
"watchListMessage": ""
}
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": true,
"note": "Wallet charged 100.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_phone",
"environment": "live",
"bvn_data": null
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": true,
"note": "Wallet charged 100.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_phone",
"environment": "live",
"bvn_data": null
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": true,
"note": "Wallet charged 100.00 NGN"
}
}A restricted outcome may include verification data. When it is unavailable, bvn_data is null.
Error responses
| HTTP | Code | When it happens |
|---|---|---|
400 | INVALID_REQUEST | Enter a valid Nigerian phone number (e.g. 08012345678 or +2348012345678) |
400 | INVALID_IDEMPOTENCY_KEY | Header is missing or does not match the required format |
401 | UNAUTHORIZED | Key is invalid, expired, revoked, or lacks BVN_VERIFY |
402 | INSUFFICIENT_BALANCE | Live wallet balance is below ₦100 |
409 | IDEMPOTENCY_KEY_REUSED | The key was used with a different request body |
409 | IDEMPOTENCY_IN_PROGRESS | The same live operation is still processing |
429 | RATE_LIMIT_EXCEEDED | Per-key request limit was exceeded |
500 | INTERNAL_ERROR | An unexpected error prevented completion |
503 | SERVICE_UNAVAILABLE | The verification service is temporarily unavailable |
Invalid request example
{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "Enter a valid Nigerian phone number (e.g. 08012345678 or +2348012345678)",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
},
"billing": {
"amount": 100,
"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": 100,
"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": 100,
"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": 100,
"currency": "NGN",
"unit": "naira",
"charged": false,
"note": "No charges"
}
}All error responses have charged: false. See Errors for retry guidance.