Basic NIN Verification

The Basic NIN Verification API allows users to verify an individual's National Identification Number (NIN) against their basic personal details to ensure identity authenticity.

Base URL

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

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

Endpoint

POST verification/api/v1/idv/basic/nin

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 basic identity information required for NIN verification.

Example Request

{
  "idDocumentNumber": "12345678901",
  "dateOfBirth": "1990-05-12",
  "firstName": "John",
  "lastName": "Doe",
  "reference": "NIN_REF_12345",
  "serviceProviderCode": "SPC001"
}

Request Body Schema

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

Responses

Success Response (200 OK)

If the verification is successful, the API returns a response indicating whether the NIN matches the provided details.

 {
  "apiVersion": "1.0",
  "success": true,
  "code": "00",
  "message": "Verification successful",
  "requestId": "REQ-987654",
  "data": {
    "isMatch": true,
    "message": "The NIN 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 NIN 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/nin" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "idDocumentNumber": "12345678901",
           "dateOfBirth": "1990-05-12",
           "firstName": "John",
           "lastName": "Doe",
           "reference": "NIN_REF_12345",
           "serviceProviderCode": "SPC001"
         }'