Integration Guide

Overview

This lookup service allows you to verify comprehensive information associated with a National Identification Number (NIN) or Virtual National Identification Number (VNIN). This guide will walk you through integrating this service into your application, giving you the ability to access and verify important NIN or VNIN-related details seamlessly.

Prerequisites

Before you begin integrating the NIN Lookup service, ensure you have the following:

Sign up on the Mono Dashboard ➡
Create an App and fetch the generated Secret Key ➡

With these prerequisites met you can proceed to integrate the NIN Lookup service into your application using the steps provided below.

Step 1: Make a NIN/VNIN Lookup Request

To retrieve NIN or VNIN-related information, send a POST request to the following endpoint:

POST https://api.withmono.com/v3/lookup/nin

Request Body Parameters

nin (required): Provide the National Identification Number (NIN or VNIN) for the lookup.

Include this parameter in the request body to specify the NIN/VNIN number for the lookup.

Request Headers

Include the following header in your request for authentication:

mono-sec-key (required): Your Mono secret key.

cURL Sample Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "mono-sec-key: YOUR_MONO_SECRET_KEY" \
  -d '{
    "nin": "NIN_NUMBER OR VNIN"
  }' \
  https://api.withmono.com/v3/lookup/nin

Step 2: Process the Response

Upon successful NIN/VNIN lookup, you will receive detailed information about the individual associated with the provided NIN, including birth details, contact information, marital status, religion, and more.

{
  "status": "successful",
  "message": "NIN Lookup Successfull",
  "data": {
    "birthcountry": "nigeria",
    "birthdate": "01-01-1990",
    "birthlga": "Lagos Mainland",
    "birthstate": "Lagos",
    "educationallevel": "tertiary",
    "email": "",
    "employmentstatus": "employed",
    "firstname": "WIGO",
    "gender": "m",
    "heigth": "150",
    "maritalstatus": "single",
    "middlename": "SAMUEL",
    "nin": "09876543212",
    "nok_address1": "3B MICHAEL WISDOM STREET",
    "nok_address2": "",
    "nok_firstname": "AISHA",
    "nok_lga": "Lagos Island",
    "nok_middlename": "",
    "nok_postalcode": "",
    "nok_state": "Lagos",
    "nok_surname": "AGBA",
    "nok_town": "FESTAC",
    "ospokenlang": "",
    "pfirstname": "",
    "photo": "/9j/4AAQSkZJRgABAgAAAQABAAD/pYH//Z",
    "pmiddlename": "",
    "profession": "ENGINEER",
    "psurname": "",
    "religion": "islam",
    "residence_address": "2A MUSA ADE STREET",
    "residence_lga": "Ogba",
    "residence_state": "Lagos",
    "residence_town": "OGBA",
    "residencestatus": "birth",
    "self_origin_lga": "",
    "self_origin_place": "",
    "self_origin_state": "",
    "signature": "/9j/4AAQSkZJRgABAQEAlgCWAAD/XYZ//2Q==",
    "spoken_language": "YORUBA",
    "surname": "MUSA",
    "telephoneno": "08012345678",
    "title": "mr",
    "userid": "",
    "vnin": "",
    "central_iD": "123456",
    "tracking_id": "ABC0DEFG5000XYZ"
  }
}

How to Generate Virtual NIN

Generating a Virtual NIN number can be achieved via two methods.

Utilizing the NIMC Application:

The NIMC mobile app requires the user to input Mono's Enterprise code or ID (696739).
The user is then prompted to scan the merchant QR code within the NIMC app.
Upon completion of the scan, the NIMC application provides the user with a virtual NIN.
Subsequently, the user enters this virtual NIN into the partner's application or designated endpoint.

Utilizing the NIMC Code:

To utilize the NIMC code, the user initiates the process by dialling the USSD shortcode (*346*3*customer NIN*696739#) from a phone number registered with NIN.
NIMC responds by delivering the NIN to the user via SMS or a session message.
The user then inputs this NIN into the partner's application or designated endpoint for further use.