Basic BVN Verification

The Basic BVN Verification allows users to verify an individual's BVN (Bank Verification Number) and obtain a basic response indicating whether the provided data matches or not.

Base URL

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

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

Endpoint

POST verification/api/v1/idv/basic/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 authentication.

Request Body

The request body contains the basic identity information needed to verify a BVN.

Example Request

{
  "idDocumentNumber": "54651333604",
  "dateOfBirth": "2000-01-01",
  "firstName": "John",
  "lastName": "Doe",
  "reference": "REF001",
  "serviceProviderCode": "SPC001"
}

Request Body Schema

Field	Type	Required	Description
idDocumentNumber	string	✅	The BVN number of the individual to verify.
dateOfBirth	string	✅	The individual's date of birth in YYYY-MM-DD format.
firstName	string	✅	The first name of the individual.
lastName	string	✅	The last name of the individual.
reference	string	✅	Unique reference number for the verification request.
serviceProviderCode	string	✅	Code identifying the service provider.

Responses

Success Response (200 OK)

If the request is successful, the API returns a basic response indicating whether the BVN matches the provided details.

  {
  "apiVersion": "1.0",
  "success": true,
  "code": "00",
  "message": "Verification successful",
  "requestId": "REQ-789456",
  "data": {
    "isMatch": true,
    "message": "The BVN matches the provided details."
  }
}

Response Schema

Field	Type	Description
apiVersion	string	API version.
success	boolean	Indicates whether the request was successful.
code	string	Response code.
message	string	Description of the response.
requestId	string	Unique ID for tracking the request.
data.isMatch	boolean	Indicates whether the provided BVN matches the input details.
data.message	string	Additional information about the match result.

Error Responses

Status Code	Description	Example Response
400	Bad Request	{ "success": false, "message": "Invalid request.", "code": "400" }
401	Unauthorized	{ "success": false, "message": "Unauthorized access.", "code": "401" }
500	Internal Server Error	{ "success": false, "message": "Server error.", "code": "500" }

Usage Example (cURL)

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