Verify National Identification Number (NIN)

NIN Verification

POST {{baseurl}}/v2/api/identity/ng/nin

Headers

Name	Type	Description
token*	String	API secret token

Name

Type

Description

token*

String

API secret token

Request Body

Name Type Description

Name	Type	Description
id*	Sting	Valid NIN
isSubjectConsent*	Boolean	Indicate subject has given consent. `Must be true`
validation	Object	Validation Object
data	Object	Validation Object
lastName	String	lastname to compare against ID
firstName	String	firstname to compare against ID
dateOfBirth	String	date of birth to compare against ID
selfie	Object	Selfie Validation Object
image	String	Selfie image to compare against ID
premiumNIN	Boolean	Whether to perform a premium (high priority) call Default value: `false`

id*

Sting

Valid NIN

isSubjectConsent*

Boolean

Indicate subject has given consent. Must be true

validation

Object

Validation Object

data

Object

Validation Object

lastName

String

lastname to compare against ID

firstName

String

firstname to compare against ID

dateOfBirth

String

date of birth to compare against ID

selfie

Object

Selfie Validation Object

image

String

Selfie image to compare against ID

premiumNIN

Boolean

Whether to perform a premium (high priority) call

Default value: false

NIN Verification

NIN verification verifies that a provided National Identity Number exists in the database. It shows the full information of the NIN holder;

{
    "id": "11111111111",
    "premiumNin": true,
    "isSubjectConsent": true
}

{
    "success": true,
    "statusCode": 200,
    "message": "success",
    "data": {
        "id": "6491edda239381d3be87a5fb",
        "address": {
            "town": "SULEJA",
            "lga": "Suleja",
            "state": "Niger",
            "addressLine": "13B Fake Street, Ilupeju Niger State"
        },
        "parentId": null,
        "status": "found",
        "reason": null,
        "dataValidation": false,
        "selfieValidation": false,
        "firstName": "Sarah",
        "middleName": "Jane",
        "lastName": "Doe",
        "image": "data:image/jpg;base64,/9j/4AAQSkZJRgABAQEBLAEsAAD/2wCEAAoHBwgHBgip3OR/1n/9k=",
        "signature": "data:image/jpg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gIcSUNREQEREH/9k=",
        "mobile": "08000000000",
        "email": null,
        "birthState": "Edo",
        "nokState": "Niger",
        "religion": "christianity",
        "birthLGA": "Esan West",
        "birthCountry": "nigeria",
        "dateOfBirth": "1988-04-04",
        "isConsent": true,
        "idNumber": "11111111111",
        "businessId": "62c2a4868d319373a6280152",
        "type": "nin",
        "allValidationPassed": true,
        "gender": "f",
        "requestedAt": "2023-06-20T18:20:11.552Z",
        "requestedById": "62c2a4868d3193700828014e",
        "country": "NG",
        "createdAt": "2023-06-20T18:20:11.657Z",
        "lastModifiedAt": "2023-06-20T18:20:11.657Z",
        "metadata": {},
        "requestedBy": {
            "firstName": "API",
            "lastName": "User",
            "middleName": "",
            "id": "62c2a4868d3193700828014e"
        }
    },
    "links": []
}

NIN Facial Matching

NIN Facial matching is used to verify that a NIN is valid and also that image provided matches with the image in the database. This includes a confidence score of the Facial matching;

{
    "id": "11111111111",
    "premiumNin": true,
    "isSubjectConsent": true,
    "validations": {
        "selfie": {
            "image": "https://cdn.youverify.co/1655466566309-lLSfNTlhElMTtbXW-QE-q.jpg"
        }
    }
}

{
    "success": true,
    "statusCode": 200,
    "message": "success",
    "data": {
        "id": "6491ee6e239381344487a5ff",
        "address": {
            "town": "SULEJA",
            "lga": "Suleja",
            "state": "Niger",
            "addressLine": "13B Fake Street, Ilupeju Niger State"
        },
        "validations": {
            "selfie": {
                "selfieVerification": {
                    "confidenceLevel": 49,
                    "threshold": 80,
                    "match": false,
                    "image": "https://cdn.youverify.co/1655466566309-lLSfNTlhElMTtbXW-QE-q.jpg"
                }
            },
            "validationMessages": "Provided image does not match ID image"
        },
        "parentId": null,
        "status": "found",
        "reason": null,
        "dataValidation": false,
        "selfieValidation": true,
        "firstName": "Sarah",
        "middleName": "Jane",
        "lastName": "Doe",
        "image": "data:image/jpg;base64,/9j/4AAQSkZJRgABAQEBLAEsAAD/2wCEAAoHBwgHBgoICAgLCgoLD4/k4dLip3OR/1n/9k=",
        "signature": "data:image/jpg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gIcSUNDX1BST0ZJTEUAAQEAAAIMbGNtcwIQAABtEQEREH/9k=",
        "mobile": "08000000000",
        "email": null,
        "birthState": "Edo",
        "nokState": "Niger",
        "religion": "christianity",
        "birthLGA": "Esan West",
        "birthCountry": "nigeria",
        "dateOfBirth": "1988-04-04",
        "isConsent": true,
        "idNumber": "11111111111",
        "businessId": "62c2a4868d319373a6280152",
        "type": "nin",
        "allValidationPassed": false,
        "gender": "f",
        "requestedAt": "2023-06-20T18:22:39.966Z",
        "requestedById": "62c2a4868d3193700828014e",
        "country": "NG",
        "createdAt": "2023-06-20T18:22:40.000Z",
        "lastModifiedAt": "2023-06-20T18:22:40.000Z",
        "metadata": {},
        "requestedBy": {
            "firstName": "API",
            "lastName": "User",
            "middleName": "",
            "id": "62c2a4868d3193700828014e"
        }
    },
    "links": []
}

NIN Validation

NIN Validation verifies a NIN and compares given data parameters against the data present in the database. For example, a first name and last name can be provided and this will validate as true or false as to whether it matches with the names in the database or not;

{
    "id": "11111111111",
    "premiumNin": true,
    "isSubjectConsent": true,
    "validations": {
        "data": {
            "lastName": "Doe",
            "firstName": "Sarah",
            "dateOfBirth": "1988-04-04"
        }
    }
}

{
    "success": true,
    "statusCode": 200,
    "message": "success",
    "data": {
        "id": "6491eed02393815e9f87a603",
        "address": {
            "town": "SULEJA",
            "lga": "Suleja",
            "state": "Niger",
            "addressLine": "13B Fake Street, Ilupeju Niger State"
        },
        "validations": {
            "data": {
                "lastName": {
                    "validated": true,
                    "value": "Doe"
                },
                "dateOfBirth": {
                    "validated": true,
                    "value": "1988-04-04"
                },
                "firstName": {
                    "validated": true,
                    "value": "Sarah"
                }
            },
            "validationMessages": ""
        },
        "parentId": null,
        "status": "found",
        "reason": null,
        "dataValidation": true,
        "selfieValidation": false,
        "firstName": "Sarah",
        "middleName": "Jane",
        "lastName": "Doe",
        "image": "data:image/jpg;base64,/9j/4AAQSkZJRgABAQEBLAEsAAD/2wCEAAoHBwgHBgoIR/1n/9k=",
        "signature": "data:image/jpg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gIcSUNDX1BSTQEREH/9k=",
        "mobile": "08000000000",
        "email": null,
        "birthState": "Edo",
        "nokState": "Niger",
        "religion": "christianity",
        "birthLGA": "Esan West",
        "birthCountry": "nigeria",
        "dateOfBirth": "1988-04-04",
        "isConsent": true,
        "idNumber": "11111111111",
        "businessId": "62c2a4868d319373a6280152",
        "type": "nin",
        "allValidationPassed": true,
        "gender": "f",
        "requestedAt": "2023-06-20T18:24:16.891Z",
        "requestedById": "62c2a4868d3193700828014e",
        "country": "NG",
        "createdAt": "2023-06-20T18:24:16.916Z",
        "lastModifiedAt": "2023-06-20T18:24:16.916Z",
        "metadata": {},
        "requestedBy": {
            "firstName": "API",
            "lastName": "User",
            "middleName": "",
            "id": "62c2a4868d3193700828014e"
        }
    },
    "links": []
}

NIN Full Sample Request

This is a sample request that contains all the parameters as described above, all in one call

{
    "id": "11111111111",
    "premiumNin": true,
    "metadata": {
        "requestId": "1209348756"
},
    "isSubjectConsent": true,
    "validations": {
        "data": {
            "lastName": "Citizen",
            "firstName": "Proud",
            "dateOfBirth": "1988-04-04"
        },
        "selfie": {
            "image": "https://cdn.youverify.co/1655466566309-lLSfNTlhElMTtbXW-QE-q.jpg"
        }
    }
}

{
    "success": true,
    "statusCode": 200,
    "message": "success",
    "data": {
        "id": "6491ef1a239381781b87a607",
        "address": {
            "town": "SULEJA",
            "lga": "Suleja",
            "state": "Niger",
            "addressLine": "13B Fake Street, Ilupeju Niger State"
        },
        "validations": {
            "data": {
                "lastName": {
                    "validated": false,
                    "value": "Ehichioya"
                },
                "dateOfBirth": {
                    "validated": false,
                    "value": "2000-01-01"
                },
                "firstName": {
                    "validated": false,
                    "value": "Prior"
                }
            },
            "selfie": {
                "selfieVerification": {
                    "confidenceLevel": 49,
                    "threshold": 80,
                    "match": false,
                    "image": "https://cdn.youverify.co/1655466566309-lLSfNTlhElMTtbXW-QE-q.jpg"
                }
            },
            "validationMessages": "First name does not match, Last name does not match, Date of birth does not match, Provided image does not match ID image"
        },
        "parentId": null,
        "status": "found",
        "reason": null,
        "dataValidation": true,
        "selfieValidation": true,
        "firstName": "Sarah",
        "middleName": "Jane",
        "lastName": "Doe",
        "image": "data:image/jpg;base64,/9j/4AAQSkZJRgABAQEBLAEsAAD/2wCEAAoHBwgHBgoIp3OR/1n/9k=",
        "signature": "data:image/jpg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gIcSUNDX1BSTEH/9k=",
        "mobile": "08000000000",
        "email": null,
        "birthState": "Edo",
        "nokState": "Niger",
        "religion": "christianity",
        "birthLGA": "Esan West",
        "birthCountry": "nigeria",
        "dateOfBirth": "1988-04-04",
        "isConsent": true,
        "idNumber": "11111111111",
        "businessId": "62c2a4868d319373a6280152",
        "type": "nin",
        "allValidationPassed": false,
        "gender": "f",
        "requestedAt": "2023-06-20T18:25:31.415Z",
        "requestedById": "62c2a4868d3193700828014e",
        "country": "NG",
        "createdAt": "2023-06-20T18:25:31.460Z",
        "lastModifiedAt": "2023-06-20T18:25:31.460Z",
        "metadata": {},
        "requestedBy": {
            "firstName": "API",
            "lastName": "User",
            "middleName": "",
            "id": "62c2a4868d3193700828014e"
        }
    },
    "links": []
}

{
    "success": true,
    "statusCode": 200,
    "message": "success",
    "data": {
        "id": "6491ef7a239381137687a60b",
        "address": {
            "town": null,
            "lga": null,
            "state": null,
            "addressLine": null
        },
        "validations": {
            "data": {
                "lastName": {
                    "validated": false,
                    "value": "Ehichioya"
                },
                "dateOfBirth": {
                    "validated": false,
                    "value": "2000-01-01"
                },
                "firstName": {
                    "validated": false,
                    "value": "Prior"
                }
            },
            "selfie": {
                "selfieVerification": {
                    "confidenceLevel": -1,
                    "threshold": 80,
                    "match": false,
                    "image": "https://cdn.youverify.co/1655466566309-lLSfNTlhElMTtbXW-QE-q.jpg"
                }
            },
            "validationMessages": ""
        },
        "parentId": null,
        "status": "not_found",
        "reason": "NIN details not found",
        "dataValidation": true,
        "selfieValidation": true,
        "firstName": null,
        "middleName": null,
        "lastName": null,
        "image": null,
        "signature": null,
        "mobile": null,
        "email": null,
        "birthState": null,
        "nokState": null,
        "religion": null,
        "birthLGA": null,
        "birthCountry": null,
        "dateOfBirth": null,
        "isConsent": true,
        "idNumber": "00000000000",
        "businessId": "62c2a4868d319373a6280152",
        "type": "nin",
        "allValidationPassed": false,
        "gender": "",
        "requestedAt": "2023-06-20T18:27:06.521Z",
        "requestedById": "62c2a4868d3193700828014e",
        "country": "NG",
        "createdAt": "2023-06-20T18:27:06.553Z",
        "lastModifiedAt": "2023-06-20T18:27:06.553Z",
        "metadata": {},
        "requestedBy": {
            "firstName": "API",
            "lastName": "User",
            "middleName": "",
            "id": "62c2a4868d3193700828014e"
        }
    },
    "links": []
}

HTTP/1.1 402 Payment Required
  {
    "success": false,
    "statusCode": 402,
    "message": "Insufficient fund",
    "name": "PaymentRequiredError",
    "data": {}
}


HTTP/1.1 500 Internal Server Error
{
    "success": false,
    "statusCode": 500,
    "message": "Service unavailable",
    "name": "Error",
    "data": {}
}

HTTP/1.1 403 Forbidden
{
    "success": false,
    "statusCode": 403,
    "message": "Permission denied",
    "name": "UnauthorizedError",
    "data": {}
}

PreviousVerify Virtual National Identification Number (vNIN)NextVerify Nigerian Driver's License (Driver's License)

Last updated 6 months ago