Verify National Identification Number (NIN)

NIN Verification

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

Headers

Name	Type	Description
token*	String	API secret token

Request Body

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

NIN Verification

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

NIN Verification Sample Request

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

NIN Verification Response

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

NIN Facial Matching Sample Request

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

NIN Facial Matching Response

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

NIN Validation Sample Request

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

NIN Validation Sample Response

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

Full Sample Request

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

Found Response:

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

Not Found Response:

Error Responses:

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