> 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 **National Identification Number** (NIN) of Nigeria as well as [NIN Verify](/docs.facephi-en/rest-api/identity-api/identity-api-reference/onboarding/kyc/nigeria/identity-verification/nin-verify.md) and, additionally, generates a **PDF copy of the NIN slip** of the holder. PDF generation is **asynchronous**: the initial response includes an object `pdf` with a `jobId` and the status `processing`. The client must query the job status through the Endpoint until the status is `completed`, at which point the **download URL** for the PDF. Note that in **Sandbox it is not returned** the field `pdf`; it only appears in **live** (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 of **11 digits**. | #### Request example ```json { "nin": "09876543212" } ``` ### 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 of 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 and the PDF generation status. See the table below. | #### Response parameters — `data` **Note:** the object `data` 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 | Holder's title. | | `firstname` | string | Name(s) of the holder. | | `middlename` | string | Middle name. | | `surname` | string | Holder's last name(s). | | `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 called `heigth` (sic): 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 | City 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 | Educational level. | | `employmentstatus` | string | Employment status. | | `religion` | string | Religion. | | `spoken_language` | string | Primary spoken language. | | `ospokenlang` | string | Other spoken language(s). | | `nok_firstname` | string | Name of the **contact next of kin** (next of kin). | | `nok_middlename` | string | Middle name of the contact next of kin. | | `nok_surname` | string | Surname of the contact next of kin. | | `nok_address1` | string | Address (line 1) of the contact next of kin. | | `nok_address2` | string | Address (line 2) of the contact next of kin. | | `nok_town` | string | City of the contact next of kin. | | `nok_lga` | string | Local Government Area (LGA) of the contact next of kin. | | `nok_state` | string | State of the contact next of kin. | | `nok_postalcode` | string | Postal code of the contact next of kin. | | `pfirstname` | string | Previous first name of the holder (if it exists; usually empty). | | `pmiddlename` | string | Previous middle name of the holder (if it exists; usually empty). | | `psurname` | string | Previous surname of the holder (if it exists; usually empty). | | `photo` | string | Holder's photo in **Base64**. | | `signature` | string | Holder's signature in format **Base64**. | | `userid` | string | Internal user identifier. | | `vnin` | string | Holder's virtual NIN (vNIN). | | `central_iD` | string | Central record identifier. The field is literally called `central_iD` (sic). | | `tracking_id` | string | Record tracking identifier. | | `pdf` | object | Generation status of the **NIN slip in PDF**. Only present in **live**. See the table below. | #### Response parameters — `data.pdf` | Parameter | Type | Description | | --------- | ------ | --------------------------------------------------------------------------------- | | `jobId` | string | Identifier of the **generation job** for the PDF. It is used to check the status. | | `status` | string | Generation status. Possible values: `processing`, `completed`. | **Note:** in **Sandbox it is not returned** the field `pdf` (empirically confirmed on 13-07-2026); in that case there is no `jobId` need to query. In **live**, the object `pdf` (`jobId`, `status`) allows *polling* the status via `GET /kyc/nga/nin/slip/{jobId}`. There are production tenants with live credentials; confirming the full PDF cycle in live requires a query with a real NIN and will be performed 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 | #### Response example (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 See the **generation job status** of the NIN slip in PDF from the `jobId` obtained in the previous response. It is recommended to check 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 that deadline. ### 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** of generation obtained in the response to the `POST`. | ### Request example ``` 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`. It expires after 7 days. | #### Response example — in progress ```json { "serviceResultCode": 200, "serviceTime": "120", "serviceResultLog": "Success", "serviceTransactionId": "c29f013g-12g0-9f1j-f64f-0g4690fh00hi", "data": { "id": "4", "status": "processing" } } ``` #### Response example — completed ```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 HTTP status code of the response): ```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 **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 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 formats. {% endhint %}