Advance BVN Verification

The Advanced BVN Verification API allows you to verify an individual's details using their Bank Verification Number (BVN). This service helps in validating identities and reducing fraud.

Base URL

https://acs-uat-verifications.amala.cloud/

https://acs-prod-verifications.amala.cloud/

Endpoint

POST verification/api/v1/idv/advance/bvn

Request Headers

You can use either the API key or Bearer Token for Authorization

Header	Type	Description
Content-Type	application/json	Specifies that the request body is in JSON format.
Authorization	Bearer <token>	Bearer Token for authentication.
x-api-key	API Key	API Key for authorization

Request Body

The request body should contain BVN details in JSON format.

Example Request

{
  "number": "12345678901",
  "firstName": "John",
  "lastName": "Doe",
  "reference": "REF123456",
  "serviceProviderCode": "SPC001"
}

Request Body Schema

Field	Type	Required	Description
number	string	✅	The BVN number of the individual.
firstName	string	✅	First name of the BVN holder.
lastName	string	✅	Last name of the BVN holder.
reference	string	✅	A unique transaction reference.
serviceProviderCode	string	✅	Code identifying the service provider.

Responses

Success Response (200 OK)

If the BVN is valid, the API returns user details as per the GetDetailOfBVNResponseApiResponse schema

{
  "apiVersion": "1.0",
  "success": true,
  "code": "00",
  "message": "Verification successful",
  "requestId": "REQ-123456",
  "data": {
    "lastName": "Doe",
    "firstName": "John",
    "middleName": "Michael",
    "gender": "Male",
    "dateOfBirth": "1990-05-15",
    "phoneNumber1": "[phone]",
    "email": "[email protected]",
    "base64Image": "base64-encoded-image-data"
  }
}

Error Responses

Status Code	Description	Example Response
400	Bad Request (Invalid BVN format)	{ "status": "error", "message": "Invalid BVN format." }
401	Unauthorized (Invalid API Key)	{ "status": "error", "message": "Unauthorized access." }
500	Internal Server Error	{ "status": "error", "message": "Something went wrong." }

Usage Example (cURL)

curl -X POST "https://acs-uat-verifications.amala.cloud/verification/api/v1/idv/advance/bvn" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "number": "12345678901",
           "firstName": "John",
           "lastName": "Doe",
           "reference": "REF123456",
           "serviceProviderCode": "SPC001"
         }'