> 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-slip.md).

# NIN Slip

Verify the **Nigerian National Identification Number** (NIN) just like [NIN Verify](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/onboarding/kyc/nigeria/identity-verification/nin-verify.md) and also generate a **PDF copy of the NIN slip** for the holder.

PDF generation is **asynchronous**: the initial response includes a `pdf` object with a `jobId` and the `processing`status. The client must poll the job status using the query endpoint until the status is `completed`, at which point the PDF **download URL** is returned. Note that in **sandbox, the** field `pdf`is not returned; it only appears in **live** mode (see note below).

### Endpoint

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

### 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 consisting of **11 digits**. |

#### Example Request

```json
{
  "nin": "09876543212"
}
```

### Responses

#### `200` Success

#### Response Parameters

| Parameter              | Type    | Description                                                                                                           |
| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`    | integer | Code indicating 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 service execution result. Includes details when an error or exception occurs in the module. |
| `serviceTransactionId` | string  | Transaction identifier associated with the request processed by the API.                                              |
| `data`                 | object  | Object containing the full NIN details and the PDF generation status. See the table below.                            |

#### Response parameters — `data`

**Note:** the `data` object is returned **without field mapping or normalization**. Field names and spelling are preserved exactly as received.

| Parameter           | Type   | Description                                                                                                                             |
| ------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `nin`               | string | National Identification Number.                                                                                                         |
| `title`             | string | Title of the holder.                                                                                                                    |
| `firstname`         | string | First name(s) of the holder.                                                                                                            |
| `middlename`        | string | Middle name.                                                                                                                            |
| `surname`           | string | Surname(s) of the holder.                                                                                                               |
| `birthdate`         | string | Date of birth.                                                                                                                          |
| `birthcountry`      | string | Country of birth.                                                                                                                       |
| `birthstate`        | string | State of birth.                                                                                                                         |
| `birthlga`          | string | Local Government Area (LGA) of birth.                                                                                                   |
| `gender`            | string | Gender.                                                                                                                                 |
| `maritalstatus`     | string | Marital status.                                                                                                                         |
| `heigth`            | string | Height in centimeters. The field is literally named `heigth` (sic): the spelling is preserved exactly as received; do not use `height`. |
| `email`             | string | Registered email address.                                                                                                               |
| `telephoneno`       | string | Registered phone number.                                                                                                                |
| `residence_address` | string | Residential address.                                                                                                                    |
| `residence_state`   | string | State of residence.                                                                                                                     |
| `residence_lga`     | string | Local Government Area (LGA) of residence.                                                                                               |
| `residence_town`    | string | Town of residence.                                                                                                                      |
| `residencestatus`   | string | Residence status.                                                                                                                       |
| `self_origin_state` | string | State of origin.                                                                                                                        |
| `self_origin_lga`   | string | Local Government Area (LGA) of origin.                                                                                                  |
| `self_origin_place` | string | Place of origin.                                                                                                                        |
| `profession`        | string | Profession.                                                                                                                             |
| `educationallevel`  | string | Education level.                                                                                                                        |
| `employmentstatus`  | string | Employment status.                                                                                                                      |
| `religion`          | string | Religion.                                                                                                                               |
| `spoken_language`   | string | Primary spoken language.                                                                                                                |
| `ospokenlang`       | string | Other spoken language(s).                                                                                                               |
| `nok_firstname`     | string | First name of the **next of kin** (next of kin).                                                                                        |
| `nok_middlename`    | string | Middle name of the next of kin.                                                                                                         |
| `nok_surname`       | string | Surname 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 surname of the holder (if any; usually empty).                                                                                 |
| `photo`             | string | Photo of the holder in **Base64**.                                                                                                      |
| `signature`         | string | Signature of the holder in **Base64**.                                                                                                  |
| `userid`            | string | Internal user identifier.                                                                                                               |
| `vnin`              | string | Holder's virtual NIN (vNIN).                                                                                                            |
| `central_iD`        | string | Central record identifier. The field is literally named `central_iD` (sic).                                                             |
| `tracking_id`       | string | Record tracking identifier.                                                                                                             |
| `pdf`               | object | Generation status of the **PDF NIN slip**. Only present in **live**mode. See the table below.                                           |

#### Response parameters — `data.pdf`

| Parameter | Type   | Description                                                    |
| --------- | ------ | -------------------------------------------------------------- |
| `jobId`   | string | PDF generation **job** identifier. Used to check the status.   |
| `status`  | string | Generation status. Possible values: `processing`, `completed`. |

**Note:** in **sandbox is not returned** the field `pdf` (empirically confirmed on 2026-07-13); in that case, there is no `jobId` to query. In **live**mode, the `pdf` (`jobId`, `status`) object allows you to *poll* the status using `GET /kyc/nga/nin/slip/{jobId}`. There are production tenants with live credentials; confirming the full PDF flow in live mode requires a query using a real NIN and will be carried out as part of QA validation with a live tenant.

#### Service Result Code

The `serviceResultCode` indicates the overall result of the service execution and reflects the **HTTP status code** of the response:

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

#### Sample response (live mode)

```json
{
  "serviceResultCode": 200,
  "serviceTime": "2100",
  "serviceResultLog": "Success",
  "serviceTransactionId": "b18e902f-01f9-8e0i-e53e-9f3589eg99gh",
  "data": {
    "nin": "09876543212",
    "title": "mr",
    "firstname": "JOHN",
    "middlename": "PAUL",
    "surname": "DOE",
    "birthdate": "15-01-1990",
    "birthcountry": "nigeria",
    "birthstate": "Lagos",
    "birthlga": "Lagos Island",
    "gender": "m",
    "maritalstatus": "single",
    "heigth": "175",
    "email": "john.doe@example.com",
    "telephoneno": "08012345678",
    "residence_address": "123 Main Street, Lagos",
    "residence_state": "Lagos",
    "residence_lga": "Ikeja",
    "residence_town": "Ikeja",
    "residencestatus": "birth",
    "self_origin_state": "Lagos",
    "self_origin_lga": "Lagos Island",
    "self_origin_place": "Lagos",
    "profession": "Engineer",
    "educationallevel": "tertiary",
    "employmentstatus": "employed",
    "religion": "christianity",
    "spoken_language": "YORUBA",
    "ospokenlang": "ENGLISH",
    "nok_firstname": "JANE",
    "nok_middlename": "",
    "nok_surname": "DOE",
    "nok_address1": "123 Main Street",
    "nok_address2": "",
    "nok_town": "Ikeja",
    "nok_lga": "Ikeja",
    "nok_state": "Lagos",
    "nok_postalcode": "100001",
    "pfirstname": "JOHN",
    "pmiddlename": "PAUL",
    "psurname": "DOE",
    "photo": "base64encodedphoto...",
    "signature": "base64encodedsignature...",
    "userid": "",
    "vnin": "AB012345678901234YZ",
    "central_iD": "12345678",
    "tracking_id": "ABC123DEF456GH",
    "pdf": {
      "jobId": "4",
      "status": "processing"
    }
  }
}
```

## Check PDF status

Check the **status of the generation job** for the PDF NIN slip using the `jobId` obtained in the previous response. We recommend checking the status **every few seconds** until it is `completed`.

**Note:** The PDF download URL **expires after 7 days** after it is generated. Download and store the document before then.

### Endpoint

```
GET /kyc/nga/nin/slip/{jobId}
```

### Authentication

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

### Path parameters

| Parameter | Type   | Required | Description                                                       |
| --------- | ------ | -------- | ----------------------------------------------------------------- |
| `jobId`   | string | **Yes**  | **Job ID** for the generation obtained in the response to `POST`. |

### Example Request

```
GET /kyc/nga/nin/slip/4
```

### Responses

#### `200` Success

#### Response parameters — `data`

| Parameter | Type   | Description                                                                                    |
| --------- | ------ | ---------------------------------------------------------------------------------------------- |
| `id`      | string | Generation job identifier.                                                                     |
| `status`  | string | Generation status. Possible values: `processing`, `completed`.                                 |
| `url`     | string | **Download URL** for the PDF. Only present when `status` is `completed`. Expires after 7 days. |

#### Example response — processing

```json
{
  "serviceResultCode": 200,
  "serviceTime": "120",
  "serviceResultLog": "Success",
  "serviceTransactionId": "c29f013g-12g0-9f1j-f64f-0g4690fh00hi",
  "data": {
    "id": "4",
    "status": "processing"
  }
}
```

#### Completed response example

```json
{
  "serviceResultCode": 200,
  "serviceTime": "110",
  "serviceResultLog": "Success",
  "serviceTransactionId": "d30g124h-23h1-0g2k-g75g-1h5701gi11ij",
  "data": {
    "id": "4",
    "status": "completed",
    "url": "https://files.example.com/nin-slips/4/nin-slip.pdf"
  }
}
```

## Error responses

The following errors apply to **both endpoints**:

#### `400` Bad Request

Error returned with the service envelope (`serviceResultCode` reflects the response's HTTP 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 **timeout**, 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 `application/problem+json`. See [Error handling](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/onboarding/kyc/nigeria.md#manejo-de-errores) for details on the three response formats.
{% endhint %}
