Basic vNIN Verification

The Basic VNIN Verification API enables users to verify an individual's VNIN (Virtual National Identity Number) and check if the provided personal details match the registered identity information

Base URL

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

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

Endpoint

POST verification/api/v1/idv/basic/vnin

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 necessary for VNIN verification.

Example Request

{
  "idDocumentNumber": "98765432101",
  "dateOfBirth": "1985-08-15",
  "firstName": "Jane",
  "lastName": "Doe",
  "reference": "VNIN_REF_002",
  "serviceProviderCode": "SPC002"
}

Request Body Schema

Field	Type	Required	Description
idDocumentNumber	string	✅	The VNIN 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 VNIN matches the provided details.

 {
  "apiVersion": "1.0",
  "success": true,
  "code": "00",
  "message": "Verification successful",
  "requestId": "REQ-987654",
  "data": {
    "isMatch": true,
    "message": "The VNIN 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 VNIN 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/vnin" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "idDocumentNumber": "98765432101",
           "dateOfBirth": "1985-08-15",
           "firstName": "Jane",
           "lastName": "Doe",
           "reference": "VNIN_REF_002",
           "serviceProviderCode": "SPC002"
         }'