NIN Verification Endpoint

Endpoint

URL: /api/ninapi

Methods: POST, GET

Description

This endpoint verifies a Nigerian National Identification Number (NIN). This is strictly a verification service.No NIN data is stored after verification. Clients are advised to save the response immediately.

Authentication

To access this endpoint, users must include their API key and secret key in the request headers.

Request Headers

  • api-key (string, required): The API key of the user.
  • secret-key (string, required): The secret key of the user.

Request Body (POST)

  • number (string, required): The NIN to verify.
  • firstLevel (string, required): The verification type.

Usage Example

See usage example in the code snippets below:

Example: Verify NIN

POST request to verify NIN:


Content-Type: application/json
api-key: your-api-key
secret-key: your-secret-key

{
"number": "12345678901",
"firstLevel": "NIN Basic", // value of this key can either be firstLevel or fId, e.g. "nin-basic" to avoid whitespace issue
}

Response:


- Status Code: 200

{
"message": "Transaction successful",
"data": {
    "status": "VERIFIED",
    "profile": {
      "nin": "12345678901",
      "surname": "DOE",
      "firstname": "JOHN",
      "middlename": "OLUWASEUN",
      "gender": "Male",
      "dateOfBirth": "1995-08-14"
    }
}}
- The `amountUsed` field represents the actual amount deducted from the user's balance based on user level.

Failed Response Format



{
"message": "Transaction failed",
"data": {
"transactionId": "1234567890",
"email": "user@example.com",
"activity": "NIN Basic",
"status": "Failed",
"recipient": "12345678901",
"amount": 100,
"initialBalance": 500,
"finalBalance": 500
"Method": API,
}
}

GET request

See usage example in the code snippets below:

Get the list of available firstLevel

GET request for available firstLevel:


Content-Type: application/json
api-key: your-api-key
secret-key: your-secret-key

Response:


- Status Code: 200

[
  {
    "available": true,
    "firstLevel": "NIN Basic",
    "fId": "nin-basic",
    "amounts": [100],
    "secondLevels": []
  },
  {
    "available": true,
    "firstLevel": "NIN Advanced",
    "fId": "nin-advanced",
    "amounts": [150],
    "secondLevels": []
  }
]

Other Error Responses

  • 401 Unauthorized: Invalid API key or secret key.
  • 404 Not Found: User not found or data not available.
  • 500 Internal Server Error: Internal server error occurred.
IABCONCEPT