> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dojah.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Virtual NIN Lookup

> Verify identity using a Virtual NIN (vNIN) from NIMC's mobile app. Returns customer details linked to the vNIN for secure, consent-based lookups.

### How does this works

* The NIN holder can generate their virtual NIN via the NIMC Mobile App or the NIMC USSD code - **\*346\*3\*NIN\*EnterpriseCode#**.
* Dojah’s Enterprise code - **1138183**
* The generated VNIN is valid for only 72 hours
* The vNIN is designed to replace the 11-digit NIN for everyday usage. It is a unique 16-character alphanumeric token comprising 12 digits, sandwiched between 4 alphabets, two on each end, with no correlation to the issuer’s Raw NIN. An example of a vNIN is: AB012345678910YZ.
* According to NIMC, The VNIN is not to be stored in any database but only used for verifying the NIN holder.

### Request

```http [GET] theme={null}
{{baseURL}}/api/v1/kyc/vnin
```

### Header

| Header        | Type   | Description                                                                                         |
| ------------- | ------ | --------------------------------------------------------------------------------------------------- |
| AppId         | string | Create an app to get your app ID on dashboard [here](https://app.dojah.io/developers/configuration) |
| Authorization | string | Private/secret key. Use `<key>` not `Bearer <key>`                                                  |

### Query parameters

| Parameter | Type   | Description                      | Required |
| --------- | ------ | -------------------------------- | -------- |
| vnin \*   | string | A uniquely generated virtual nin | required |

### Sample response

```json Response theme={null}
{
    "entity": {
        "vnin": "AB012345678910YZ",
        "firstname": "John",
        "middlename": "Doe",
        "surname": "Musa",
        "user_id": "WXABCD-1234",
        "gender": "M",
        "mobile": "08012345678",
        "dateOfBirth": "YYYY-MM-DD",
        "photo": "/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDAAgGBgc..."
    }
}
```

### Response Fields

| Field              | Type   | Description                                  |
| ------------------ | ------ | -------------------------------------------- |
| entity             | object | Contains the vNIN holder's identity details  |
| entity.vnin        | string | Virtual NIN used for the lookup              |
| entity.firstname   | string | First name of the vNIN holder                |
| entity.middlename  | string | Middle name of the vNIN holder               |
| entity.surname     | string | Surname of the vNIN holder                   |
| entity.user\_id    | string | Unique user identifier assigned by NIMC      |
| entity.gender      | string | Gender of the vNIN holder                    |
| entity.mobile      | string | Mobile phone number linked to the vNIN       |
| entity.dateOfBirth | string | Date of birth in YYYY-MM-DD format           |
| entity.photo       | string | Base64-encoded photograph of the vNIN holder |

### Test Credentials for Sandbox

Sample = `AB012345678910YZ`