> For the complete documentation index, see [llms.txt](https://truztcube.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://truztcube.gitbook.io/docs/verification-services/nin-lookup.md).

# NIN Lookup

This page contains information about how to integrate the NIN verification services into your application.

To carry out a National Identification Number (NIN) lookup, choose any of the channels below that align with your sector or industry to submit your verification request.

### API Endpoints

BASE\_API: [https://api.truztcube.com](https://api.truztcube.com/v1/nin/lookup)

### **Access Levels & Data Minimization**

According to **NIMC compliance requirements**, verification APIs are designed with **tiered access levels**. Each access level determines the **type and amount of information** returned per verification request.

This structure enforces the **Data Minimization** principle of the data protection policy. It ensures that:

* **Only relevant data** is shared with the relying party.
* **Sensitive or unnecessary information** is never exposed beyond the authorized scope.
* **Compliance** with data privacy regulations is maintained at all times.

<table><thead><tr><th width="135.22943115234375">Access Level</th><th width="395.0093994140625">Data</th><th>Credit Units for Verification</th></tr></thead><tbody><tr><td>Level 1</td><td>Photograph, Names (First, Middle, Last Names), D.O.B., Gender</td><td>5</td></tr><tr><td>level 2</td><td>Level 1 + Address, Signature, Phone Number</td><td>8</td></tr><tr><td>Level 3</td><td>Level 2 + Maiden Name, Birth Country, Birth State, Birth LGA</td><td>12</td></tr><tr><td>Level 4</td><td>Level 3 + Origin State, Origin LGA, Next Of Kin Data, And All Modifications Carried Out As At The Date Of Verification</td><td>15</td></tr><tr><td>Level 5</td><td>Level 4 + Local Government and biometrics Security information inquiries</td><td>20</td></tr></tbody></table>

### Verification Channels

Below are the various supported means of verification.

{% tabs %}
{% tab title="RAW NIN " %}
**IMPORTANT:** <mark style="color:red;">This verification system is exclusively for use by government agencies and financial institutions, as mandated by the regulator.</mark>

### Request Headers

<table><thead><tr><th width="110.94183349609375">Name</th><th width="80.968017578125">Type</th><th>Description</th></tr></thead><tbody><tr><td>x-api-key*</td><td>string</td><td>Your organization's secret API key for authentication is available on your <a href="https://truztcube.com/">Truztcube</a> dashboard.</td></tr><tr><td>method<mark style="color:red;">*</mark></td><td>string</td><td>POST</td></tr></tbody></table>

### Request Body

All the params listed below are required.

<table><thead><tr><th width="182.75225830078125">Name</th><th width="111.8658447265625">Type</th><th>Description</th></tr></thead><tbody><tr><td>nin</td><td>string</td><td>unique 11 digits issued by the NIMC to the ID holder</td></tr><tr><td>requestReason</td><td>enum</td><td>Reason for the verification check: Please review the <a href="#verification-reasons">linked document</a> for the list of reasons and select the one that applies to your use case. <a href="#verification-reasons">see the link below for approved reasons</a>.</td></tr><tr><td>enterpriseId</td><td>string</td><td>Unique code provided to an authorized enterprise, which can be found on the NINAuth dashboard</td></tr></tbody></table>

### Sample CURL Request

Substitute the values with test/live information gotten from your [Truztcube](https://truztcube.com/) dashboard

```javascript
curl --location --request POST 'https://api.truztcube.com/v1/nin/raw/lookup' \
--header 'x-api-key: sk_test_748131500a0f68647533865a16f9c4ea9866df792c588db7b169110c72cc6395' \
--header 'Content-Type: application/json' \
--data '{
    "nin":"12345678901",
    "requestReason": "nyscCheck",
    "enterpriseId": "ENT4SANDBOX"
}'

```

### Successful CURL Response.

```json
{
  "status": 200,
  "success": true,
  "message": "successfully fetched user data",
  "data": {
    "biographicData": {
      "birthCountry": "nigeria",
      "birthLga": "Utopia",
      "birthState": "Bendel",
      "dateOfBirth": "01-01-1900",
      "educationLevel": "tertiary",
      "employmentStatus": "unemployed",
      "firstName": "JOHN",
      "gender": "m",
      "height": "169",
      "lastName": "DOE",
      "maritalStatus": "single",
      "middleName": "Mary",
      "nativeSpokenLanguage": "English",
      "nextOfKinAddressLine1": "NO. 22 Aso Villa",
      "nextOfKinFirstName": "Mary",
      "nextOfKinLga": "Utopia",
      "nextOfKinMiddleName": "Doe",
      "nextOfKinSurname": "Jane",
      "nextOfKinTown": "Kano",
      "originLga": "Arochukwu",
      "originPlace": "OKPOGA",
      "originState": "LAGOS",
      "profession": "STUDENT",
      "religion": "christianity",
      "residenceAddressLine1": "NO. 22 ASO Villa",
      "residenceLga": "Abuja",
      "residenceState": "Benue",
      "residenceStatus": "birth",
      "residenceTown": "Barkin Chiawa",
      "title": "Mr"
    },
    "biometricData": [
      {
        "biometricSubType": "face",
        "biometricType": "photo",
        "image":"/sm71.."
      },
      {
        "biometricSubType": "signature",
        "biometricType": "signature",
        "image": "/9j/4AAQSkZ.."
      }
    ],
    "contactData": {
      "phone1":  "08030000000"
    }
  }
}


```

{% endtab %}

{% tab title="SHARE CODE" %}
The ShareCode verification method is the regulator-approved process for public NIN verification. It requires the NIN holder to generate and share a code from the NINAuth mobile app, which relying parties can use to confirm their identity.     &#x20;

### Request Headers

<table><thead><tr><th width="120.16546630859375">Name</th><th width="83.473876953125">Type</th><th width="294.3126220703125">Description</th><th>Value</th></tr></thead><tbody><tr><td>x-api-key</td><td>string</td><td>Your organization's secret API key for authentication is available on your <a href="https://truztcube.com/">Truztcube</a> dashboard.</td><td>LIVE_JnOvILzR5HeOoBL55jkRl2h6Vbjaog</td></tr><tr><td>method</td><td>string</td><td>request method</td><td>POST</td></tr></tbody></table>

### Request Body

All the params listed below are required.

<table><thead><tr><th width="137.8673095703125">Name</th><th width="84.35382080078125">Type</th><th width="328.76214599609375">Description</th><th>Value</th></tr></thead><tbody><tr><td>shareCode</td><td>string</td><td>Code generated from the NINAuth app by the ID owner.</td><td>AB12DEC</td></tr><tr><td>requestReason</td><td>enum</td><td>Reason for the verification check: Please review the <a href="#verification-reasons">linked document</a> for the list of reasons and select the one that applies to your use case. <a href="#verification-reasons">see the link below for approved reasons</a>.</td><td>eg [ 'nyscCheck', legalCheck'] etc </td></tr><tr><td>enterpriseId</td><td>string</td><td>Unique code provided to authorized enterprises, which canbe  found on the NINAuth dashboard</td><td></td></tr></tbody></table>

### Sample CURL Request

Substitute the values with test/live information gotten from your [Truztcube](https://truztcube.com/) dashboard

```javascript
 curl --location 'https://api.truztcube.com/v1/nin/sharecode/lookup' \
--header 'x-api-key: sk_test_748131500a0f68647533865a16f9c4ea9866df792c588db7b169110c72cc6395' \
--header 'Content-Type: application/json' \
--data '{
    "shareCode": "ABCDEF-12345",
    "requestReason": "nyscCheck",
    "enterpriseId": "ENT4SANDBOX"
}'
```

### Sample Curl Response

```json
{
  "status": 200,
  "success": true,
  "message": "successfully fetched user data",
  "data": {
    "biographicdata": {
      "dateofbirth": "01-00-1900",
      "firstname": "John",
      "gender": "m",
      "lastname": "Doe",
      "middlename": "Peter"
    },
    "biometricdata": [
      {
        "biometricSubType": "face",
        "biometricType": "photo",
        "image": "/9j/4AAQSkZJRgABAgAAAQABAAD..."
      }
    ],
    "consentID": "bf874bb8-97ca-40c5-a9f1",
    "contactdata": {
      "phone1": "080123456789"
    },
    "requestID": "YPT27634JJH"
  }
}

```

{% endtab %}
{% endtabs %}

### Error Format

{% tabs %}
{% tab title="Error" %}

```json
{
    "statusCode": 500,
    "message": "Request failed: Request failed with status code 500."
}

```

{% endtab %}
{% endtabs %}

### Verification Reasons

```
curl --location 'https://api.truztcube.com/v1/nin/request-reasons'
--header 'x-api-key: sk_test_748131500a0f68647533865a16f9c4ea9866df792c588db7b169110c72cc6395' \
--header 'method: GET'\

```

The array below lists the values needed for request\_reason in your verification. Please include the key value with your submission.

```json
"data": [
    {
      "key": "taxationEnrollment",
      "label": "Taxation Enrollment"
    },
    {
      "key": "taxationAssessment",
      "label": "Taxation Assessment"
    },
    {
      "key": "taxationEnforcement",
      "label": "Taxation Enforcement"
    },
    {
      "key": "corporateAffairsDirector",
      "label": "Corporate Affairs Director"
    },
    {
      "key": "corporateAffairsShareholder",
      "label": "Corporate Affairs Shareholder"
    },
    {
      "key": "corporateAffairsTrustee",
      "label": "Corporate Affair Trustee"
    },
    {
      "key": "medical",
      "label": "Medical"
    },
    {
      "key": "educationExam",
      "label": "Education Exam"
    },
    {
      "key": "educationAdmission",
      "label": "Education Admission"
    },
    {
      "key": "educationPromotion",
      "label": "Education Promotion"
    },
    {
      "key": "employmentRecruitment",
      "label": "Employment Recruitment"
    },
    {
      "key": "employmentEnrollment",
      "label": "Employment Enrollment"
    },
    {
      "key": "employmentDismissal",
      "label": "Employment Dismissal"
    },
    {
      "key": "creditBackgroundCheck",
      "label": "Credit Background Check"
    },
    {
      "key": "financialProducts",
      "label": "Financial Products"
    },
    {
      "key": "insurance",
      "label": "Insurance"
    },
    {
      "key": "clearanceForPoliticalOffice",
      "label": "Clearance For Policitive Office"
    },
    {
      "key": "legalCourts",
      "label": "Legal Courts"
    },
    {
      "key": "legalEnrollment",
      "label": "Legal Enrollment"
    },
    {
      "key": "crimePrisonIncarceration",
      "label": "Crime Prison Incarceration"
    },
    {
      "key": "passportImmigration",
      "label": "Passport Immigration"
    },
    {
      "key": "pensionEnrollment",
      "label": "Pension Enrollment"
    },
    {
      "key": "socioCulturalEnrollment",
      "label": "Socio-cultural Enrollment"
    },
    {
      "key": "entertainment",
      "label": "Entertainment"
    },
    {
      "key": "physicalAccess",
      "label": "Physical Access"
    },
    {
      "key": "logicalVirtualAccess",
      "label": "Logical Virtual Access"
    },
    {
      "key": "telecommunicationSimReg",
      "label": "Telecommunication Sim Registration"
    },
    {
      "key": "telecommunicationIotReg",
      "label": "Telecommunication Iot Registration"
    },
    {
      "key": "aviationTransport",
      "label": "Aviation Transport"
    },
    {
      "key": "roadTransport",
      "label": "Road Transport"
    },
    {
      "key": "maritimeTransport",
      "label": "Maritime Transport"
    },
    {
      "key": "railwayTransport",
      "label": "Railway Transport"
    },
    {
      "key": "leaCheck",
      "label": "Lea Check"
    },
    {
      "key": "defence",
      "label": "Defence"
    },
    {
      "key": "nyscCheck",
      "label": "NYSC Check"
    },
    {
      "key": "efccCheck",
      "label": "EFCC Check"
    },
    {
      "key": "blacklistPolitical",
      "label": "Blacklist Political"
    },
    {
      "key": "blacklistSocial",
      "label": "Blacklist Social"
    }
  ]
}
```