Verify National Identification Number (NIN)

NIN Verification

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

Headers

NameTypeDescription

token*

String

API secret token

Request Body

NameTypeDescription

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": []
}
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": {}
}

Last updated