Verify Tax PIN

This section contains api endpoint to verify a Kenyan tax PIN number, as well as request and response sample

Identity Verification

POST {{baseurl}}/v2/api/identity/ke/pin-check

Headers

Name	Type	Description
token*	String	API secret token

Request Body

Name	Type	Description
id*	String	Candidates pin number
isSubjectConsent*	Boolean	Indicate subject has given consent. Must be true
metadata	Object	Metadata object. Any valid object can be passed here. It gets returned as is.

Verify Tax Pin

This is used to verify that a provided Kenyan Tax PIN exists in the database. It shows the information of the taxpayer.

Tax PIN Verification Found Sample

This contains a request and response sample of a valid and existing tax pin.

Tax PIN Sample Request

{
    "id":"A012345678R",
    "isSubjectConsent":true,
}

Tax PIN Sample Response

{
    "success": true,
    "statusCode": 200,
    "message": "success",
    "data": {
        "id": "6416e5258c8eb062f325a87c",
        "parentId": null,
        "status": "found",
        "reason": null,
        "dataValidation": false,
        "selfieValidation": false,
        "pin": "A012345678R",
        "pinCurrentStatus": "Registered",
        "effectiveFromDate": "2013-12-31",
        "effectiveToDate": null,
        "itaxStatus": "iPage Updated",
        "obligationName": "Income Tax - Resident Individual",
        "pinStatus": "Active",
        "taxpayerName": "John Doe",
        "isConsent": true,
        "businessId": "628b38f03ae28a14f52d4bf7",
        "type": "kePinCheck",
        "allValidationPassed": true,
        "requestedAt": "2023-03-19T10:34:14.297Z",
        "requestedById": "628b38f03ae28a5a122d4bf3",
        "country": "KE",
        "createdAt": "2023-03-19T10:34:14.485Z",
        "lastModifiedAt": "2023-03-19T10:34:14.485Z",
        "metadata": {},
        "requestedBy": {
            "firstName": "API",
            "lastName": "User",
            "middleName": "",
            "id": "628b38f03ae28a5a122d4bf3"
        }
    },
    "links": []
}

Tax PIN Verification Not Found Sample

This contains a response sample of a non-existing tax pin.

Not Found Sample Response

{
    "success": true,
    "statusCode": 200,
    "message": "success",
    "data": {
        "id": "6416e618d34a0c637adbef4f",
        "parentId": null,
        "status": "not_found",
        "reason": "Invalid pin, please check your pin and try again.",
        "dataValidation": false,
        "selfieValidation": false,
        "pin": null,
        "pinCurrentStatus": null,
        "effectiveFromDate": null,
        "effectiveToDate": null,
        "itaxStatus": null,
        "obligationName": null,
        "pinStatus": null,
        "taxpayerName": null,
        "isConsent": true,
        "businessId": "628b38f03ae28a14f52d4bf7",
        "type": "kePinCheck",
        "allValidationPassed": false,
        "requestedAt": "2023-03-19T10:38:42.145Z",
        "requestedById": "628b38f03ae28a5a122d4bf3",
        "country": "KE",
        "createdAt": "2023-03-19T10:38:42.359Z",
        "lastModifiedAt": "2023-03-19T10:38:42.359Z",
        "metadata": {},
        "requestedBy": {
            "firstName": "API",
            "lastName": "User",
            "middleName": "",
            "id": "628b38f03ae28a5a122d4bf3"
        }
    },
    "links": []
}

Error Response

{
  "success": false,
  "statusCode": 404,
  "message": "You have attempted to get a resource that does not exist.",
  "name": "ResourceNotFoundError",
  "data": {}
}