Advance vNIN Verification

The Advance VNIN Verification API allows you to verify an individual's details using their Virtual National Identification Number (VNIN). This helps in identity validation and fraud prevention.

Base URL

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

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

Endpoint

POST verification/api/v1/idv/advance/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 should contain VNIN details in JSON format.

Example Request

{
  "number": "12345678901",
  "firstName": "Jane",
  "lastName": "Doe",
  "reference": "REF789012",
  "serviceProviderCode": "SPC002"
}

Request Body Schema

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

Responses

Success Response (200 OK)

If the VNIN is valid, the API returns user details as per the GetDetailsOfNINResponseApiResponse schema.

{
  "apiVersion": "1.0",
  "success": true,
  "code": "00",
  "message": "Verification successful",
  "requestId": "REQ-789012",
  "data": {
    "surname": "Doe",
    "firstName": "Jane",
    "middleName": "Elizabeth",
    "gender": "Female",
    "birthDate": "1995-07-20",
    "telephoneno": "[phone]",
    "email": "[email protected]",
    "employmentStatus": "Employed",
    "residenceAddress": "123 Main Street",
    "residenceTown": "Lagos",
    "residenceLga": "Ikeja",
    "residenceState": "Lagos",
    "nokSurname": "Smith",
    "nokFirstName": "John",
    "nokMiddlename": "Michael",
    "nokAddress1": "456 Elm Street",
    "nokTown": "Abuja",
    "nokLga": "Garki",
    "nokPostalcode": "900001",
    "nokState": "FCT",
    "photo": "base64-encoded-image-data"
  }
}

Error Responses

Status Code	Description	Example Response
400	Bad Request (Invalid VNIN format)	{ "status": "error", "message": "Invalid VNIN 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/vnin" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "number": "12345678901",
           "firstName": "Jane",
           "lastName": "Doe",
           "reference": "REF789012",
           "serviceProviderCode": "SPC002"
         }'