NIN Verification API

API Description

Objective

The NIN Verification API, or the VNIN verification API, retrieves a user's personally identifiable information(PII) based on their Nigerian national identification number(NIN).

Input	Output
The user's NIN.	Name National Identification Number (NIN) Birth date and location Educational Level Email Employment status Gender and height Marital status Next of Kin's Name and Address	Language details Photo Profession Religion Residence address Signature Telephone Number Title Central ID Tracking ID

Did you know?

The National Identification Number (NIN) consists of 11 non-intelligible numbers assigned to an individual at the completion of enrolment into the National Identity Database (NIDB) that is maintained by the National Identity Management Commission(NIMC).

API URL

https://zaf.thomas.hyperverge.co/v1/ninFetch

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload.	application/json
appId	Mandatory	The application identifier shared by HyperVerge.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey.	This should be both unique and easily associated with the specific user's interaction in your application(s).

Input

The following table provides the complete information on the parameters used in the request body for the API calls.

Parameter	Mandatory or Optional	Allowed Values	Default Value	Description
nin	Mandatory	It should have eleven digits	Not Applicable	The user's NIN.

Sample Request

The following section shows the standard curl request for the API.

curl --location --request POST 'https://zaf.thomas.hyperverge.co/v1/ninFetch' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "nin": "<Enter_the_NIN>"
}'

Success Response Sample

The following is a sample response from the API.

{
  "result": {
    "status": "successful",
    "message": "Lookup Successful",
    "data": {
      "birthcountry": "nigeria",
      "birthdate": "07-11-1992",
      "birthlga": "Mushin",
      "birthstate": "Lagos",
      "educationallevel": "tertiary",
      "email": "<email_placeholder>",
      "emplymentstatus": "employed",
      "firstname": "OLUWAFUNMIBI",
      "gender": "m",
      "heigth": "169",
      "maritalstatus": "single",
      "middlename": "LAWRENCE",
      "nin": "<nin_placeholder>",
      "nok_address1": "216 BASTABLE AVENUE BARKING",
      "nok_address2": "",
      "nok_firstname": "OMOTOWOBOLA",
      "nok_middlename": "AGATAR",
      "nok_surname": "YEDENU-MARTINS",
      "nok_town": "LONDON",
      "nspokenlang": "YORUBA",
      "ospokenlang": "FRENCH",
      "othername": "SULAIMON",
      "photo": "<photo_url_placeholder>",
      "profession": "MASS COMMUNICATION",
      "religion": "christianity",
      "residence_AdressLine1": "3 ODOFIN CLOSE",
      "residence_Town": "ILASAMAJA",
      "residence_lga": "Mushin",
      "residence_state": "Lagos",
      "residencestatus": "birth",
      "self_origin_lga": "Yewa North",
      "self_origin_place": "YEWA",
      "self_origin_state": "Ogun",
      "signature": "<signature_url_placeholder>",
      "surname": "OSAYEMI",
      "telephoneno": "<phone_number_placeholder>",
      "title": "mr",
      "central_iD": "<central_id_placeholder>",
      "tracking_id": "<tracking_id_placeholder>"
    }
  },
  "status": "success",
  "statusCode": 200,
  "metaData": {
    "requestId": "<request_id_placeholder>"
  }
}

Success Response Details

The following table provides the details of the fields in a success response.

Response	Description
birthcountry	The user's country of birth.
birthdate	The date on which the individual was born.
birthlga	Local Government Area (LGA) of the individual's birth.
birthstate	The state in Nigeria where the individual was born.
educationallevel	The highest level of education attained by the individual.
email	The email address associated with the individual's identity.
employmentstatus	The current employment status of the individual (e.g., employed, unemployed, student).
firstname	The first name of the individual.
middlename	The middle name of the individual.
gender	The gender of the individual (e.g., male or female).
height	The height of the individual.
maritalstatus	The marital status of the individual (e.g., married, single, divorced).
nin	The National Identification Number, a unique identification number assigned to individuals.
nok_address1	Address details of the next of kin (NOK) - line 1.
nok_address2	Address details of the next of kin (NOK) - line 2.
nok_firstname	First name of the next of kin.
nok_middlename	Middle name of the next of kin.
nok_surname	Surname of the next of kin.
nok_lga	Local Government Area (LGA) of the next of kin.
nok_postalcode	Postal code of the next of kin.
nok_state	State of residence of the next of kin.
nok_town	Town of residence of the next of kin.
ospokenlang	Official spoken language(s) of the individual.
photo	A photograph of the individual.
profession	The individual's profession or occupation.
religion	The religion to which the individual adheres.
residence_address	The current residential address of the individual.
residence_lga	Local Government Area (LGA) of the individual's residence.
residence_state	The state in Nigeria where the individual currently resides.
residence_town	The town or city where the individual currently resides.
self_origin_lga	Local Government Area (LGA) of the individual's origin.
self_origin_place	Place of origin of the individual.
self_origin_state	State of origin of the individual.
signature	The individual's signature.
telephoneno	The telephone number of the individual.
title	The title or honorific of the individual (e.g., Mr., Mrs., Dr.).
vnin	Virtual National Identification Number.
central_iD	Central Identification (ID) associated with the individual.
tracking_id	A unique identifier used for tracking purposes.

Failure Response Sample

The following is a sample response for no matching records found against the NIN input.

{
  "result": {
    "status": "failed",
    "message": "Sorry, lookup failed. Please check the details and try again"
  },
  "status": "failure",
  "statusCode": 400,
  "metaData": {
    "requestId": "1702388746563-62ed2d28-ff89-41fe-b27b-ff7c1be197e2"
  }
}

Error Response Samples

The following is the sample error response from the API.

Incorrect Length

{
"message": "Input Validation Error: does not meet minimum length of 11",
"statusCode": 400,
"status": "failure"
}

Failure and Error Response Details

A failure or error response from the API contains a failure status with a relevant status code and error message.

The following table summarizes all the error and failure responses.

Status Code	Error Message	Error Description
400	Input Validation Error: does not meet minimum length of 11	Please check the length of the NIN in the request.
400	Sorry, lookup failed. Please check the details and try again	The request has an invalid NIN that yielded no match in the database.