> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/onboarding/kyc/nigeria/identity-verification/nin-verify.md).

# NIN Verify

Verify the **National Identification Number** of Nigeria's (NIN) and returns the holder's information including data **biometric and demographic**.

### Endpoint

```
POST /kyc/nga/nin
```

### Authentication

| Type    | Location | Name          |
| ------- | -------- | ------------- |
| API Key | Header   | **x-api-key** |

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter | Type   | Required | Description                                      |
| --------- | ------ | -------- | ------------------------------------------------ |
| `nin`     | string | **Yes**  | National Identification Number of **11 digits**. |

#### Request example

```json
{
  "nin": "12345678901"
}
```

### Responses

#### `200` Success

#### Response parameters

| Parameter              | Type    | Description                                                                                                                    |
| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `serviceResultCode`    | integer | Code that indicates the **overall result** of the service execution. See [Service Result Code](#service-result-code)           |
| `serviceTime`          | string  | Processing time **(milliseconds)**.                                                                                            |
| `serviceResultLog`     | string  | Descriptive field for the result of the service execution. Includes details when there is an error or exception in the module. |
| `serviceTransactionId` | string  | Transaction identifier associated with the request processed by the API.                                                       |
| `data`                 | object  | Object with the complete NIN data. See table below.                                                                            |

#### Response parameters — `data`

The fields of `data` are returned **as provided by the national registry** (lowercase names, unnormalized). Fields without data are returned as an empty string (`""`).

| Parameter           | Type   | Description                                                    |
| ------------------- | ------ | -------------------------------------------------------------- |
| `nin`               | string | National Identification Number.                                |
| `firstname`         | string | Holder's first name(s).                                        |
| `middlename`        | string | Middle name.                                                   |
| `surname`           | string | Holder's last name(s).                                         |
| `title`             | string | Personal title (e.g. `mr`, `mrs`).                             |
| `gender`            | string | Gender. Possible values: `m`, `f`                              |
| `birthdate`         | string | Date of birth (format `DD-MM-YYYY`).                           |
| `birthcountry`      | string | Country of birth.                                              |
| `birthstate`        | string | State of birth.                                                |
| `birthlga`          | string | Local Government Area (LGA) of birth.                          |
| `maritalstatus`     | string | Marital status.                                                |
| `educationallevel`  | string | Educational level.                                             |
| `employmentstatus`  | string | Employment status.                                             |
| `profession`        | string | Profession.                                                    |
| `religion`          | string | Religion.                                                      |
| `heigth`            | string | Height in centimeters. (sic — field name as received).         |
| `email`             | string | Email address.                                                 |
| `telephoneno`       | string | Phone number.                                                  |
| `residence_address` | string | Residence address.                                             |
| `residence_town`    | string | Residence town.                                                |
| `residence_lga`     | string | Local Government Area (LGA) of residence.                      |
| `residence_state`   | string | State of residence.                                            |
| `residencestatus`   | string | Residency status (e.g. `birth`).                               |
| `self_origin_place` | string | Place of origin.                                               |
| `self_origin_lga`   | string | Local Government Area (LGA) of origin.                         |
| `self_origin_state` | string | State of origin.                                               |
| `spoken_language`   | string | Primary language.                                              |
| `ospokenlang`       | string | Other languages spoken.                                        |
| `nok_firstname`     | string | Name of the next of kin.                                       |
| `nok_middlename`    | string | Middle name of the next of kin.                                |
| `nok_surname`       | string | Last name of the next of kin.                                  |
| `nok_address1`      | string | Address (line 1) of the next of kin.                           |
| `nok_address2`      | string | Address (line 2) of the next of kin.                           |
| `nok_town`          | string | Town of the next of kin.                                       |
| `nok_lga`           | string | Local Government Area (LGA) of the next of kin.                |
| `nok_state`         | string | State of the next of kin.                                      |
| `nok_postalcode`    | string | Postal code of the next of kin.                                |
| `pfirstname`        | string | Previous first name of the holder (if any; usually empty).     |
| `pmiddlename`       | string | Previous middle name of the holder (if any; usually empty).    |
| `psurname`          | string | Previous last name of the holder (if any; usually empty).      |
| `vnin`              | string | Virtual NIN (vNIN), if one was used in the query.              |
| `userid`            | string | User identifier in the registry (usually empty).               |
| `central_iD`        | string | Central registry identifier. (sic — field casing as received). |
| `tracking_id`       | string | Request tracking identifier in the registry.                   |
| `photo`             | string | Holder's photo in format **Base64**.                           |
| `signature`         | string | Holder's signature in format **Base64**.                       |

#### Service Result Code

The `serviceResultCode` indicates the overall result of the service execution:

| serviceResultCode | Description                                                                       | HTTP code |
| ----------------- | --------------------------------------------------------------------------------- | --------- |
| 200               | The service execution was successful, the module processed the request correctly. | 200       |

#### Response example

```json
{
  "serviceResultCode": 200,
  "serviceTime": "2000",
  "serviceResultLog": "Success",
  "serviceTransactionId": "a07d891e-90e8-7d9h-d42d-8e2478df88fg",
  "data": {
    "nin": "12345678901",
    "firstname": "JOHN",
    "middlename": "PAUL",
    "surname": "DOE",
    "title": "mr",
    "gender": "m",
    "birthdate": "15-01-1990",
    "birthcountry": "nigeria",
    "birthstate": "Lagos",
    "birthlga": "Lagos Mainland",
    "maritalstatus": "single",
    "educationallevel": "tertiary",
    "employmentstatus": "employed",
    "profession": "ENGINEER",
    "religion": "christianity",
    "heigth": "175",
    "email": "",
    "telephoneno": "08012345678",
    "residence_address": "2A MUSA ADE STREET",
    "residence_town": "OGBA",
    "residence_lga": "Ogba",
    "residence_state": "Lagos",
    "residencestatus": "birth",
    "self_origin_place": "",
    "self_origin_lga": "",
    "self_origin_state": "",
    "spoken_language": "YORUBA",
    "ospokenlang": "",
    "nok_firstname": "AISHA",
    "nok_middlename": "",
    "nok_surname": "AGBA",
    "nok_address1": "3B MICHAEL WISDOM STREET",
    "nok_address2": "",
    "nok_town": "FESTAC",
    "nok_lga": "Lagos Island",
    "nok_state": "Lagos",
    "nok_postalcode": "",
    "pfirstname": "",
    "pmiddlename": "",
    "psurname": "",
    "vnin": "",
    "userid": "",
    "central_iD": "123456",
    "tracking_id": "ABC0DEFG5000XYZ",
    "photo": "base64encodedphoto...",
    "signature": "base64encodedsignature..."
  }
}
```

#### `400` Bad Request

Error returned with the service envelope (`serviceResultCode` reflects the HTTP response code):

```json
{
  "serviceResultCode": 400,
  "serviceResultLog": "Sorry, lookup failed. Please check the details and try again",
  "serviceTime": "151",
  "serviceTransactionId": "08ac9699-dc9e-4cdc-81d7-264f71838309"
}
```

#### `502` Bad Gateway

Returned when the service is temporarily unavailable or its response could not be interpreted. The body uses the service envelope with `serviceResultCode: 500`:

```json
{
  "serviceResultCode": 500,
  "serviceResultLog": "Service temporarily unavailable. Please try again later",
  "serviceTime": "3000",
  "serviceTransactionId": "38de2932-0f2h-7gff-14g0-597h04161632"
}
```

#### `504` Gateway Timeout

Timeout **error**, returned with the service envelope:

```json
{
  "serviceResultCode": 504,
  "serviceResultLog": "Request timeout. Please try again",
  "serviceTime": "30000",
  "serviceTransactionId": "48ef3043-1g3i-8hgg-25h1-608i15272743"
}
```

{% hint style="info" %}
Authentication errors (`401`/`403`) are rejected by the **gateway before reaching the service** and **do not** use the envelope `serviceResultCode`. Platform validation errors use the format `application/problem+json`. See [Error handling](/docs.facephi-en/rest-api/identity-api/identity-api-reference/onboarding/kyc/nigeria.md#manejo-de-errores) for details on the three response forms.
{% endhint %}