For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Skip to content

NIN Slip

Verify the Nigerian National Identification Number (NIN) just like NIN Verify 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 processingstatus. 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 pdfis 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

{
  "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

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 livemode. 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 livemode, 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)

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

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

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

Completed response example

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):

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:

504 Gateway Timeout

Timeout timeout, returned with the service envelope:

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 for details on the three response formats.

Last updated