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"
         }'

Last updated