# Verify Tax PIN

## Identity Verification

<mark style="color:green;">`POST`</mark> `{{baseurl}}/v2/api/identity/ke/pin-check`

#### Headers

| Name                                    | Type   | Description      |
| --------------------------------------- | ------ | ---------------- |
| token<mark style="color:red;">\*</mark> | String | API secret token |

#### Request Body

| Name                                               | Type    | Description                                                                      |
| -------------------------------------------------- | ------- | -------------------------------------------------------------------------------- |
| id<mark style="color:red;">\*</mark>               | String  | Candidates pin number                                                            |
| isSubjectConsent<mark style="color:red;">\*</mark> | Boolean | Indicate subject has given consent. <mark style="color:red;">Must be true</mark> |
| metadata                                           | Object  | Metadata object. Any valid object can be passed here. It gets returned as is.    |

### <mark style="color:purple;">Verify Tax Pin</mark>&#x20;

This is used to **verify that a provided Kenyan&#x20;**<mark style="color:orange;">**Tax PIN**</mark>**&#x20;exists in the database**. It shows the information of the taxpaye&#x72;**.**

### <mark style="color:purple;">Tax PIN Verification Found Sample</mark>

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

{% tabs %}
{% tab title="Tax PIN Sample Request" %}

```json
{
    "id":"A009274632R",
    "isSubjectConsent":true
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Tax PIN  Sample Response" %}

```json
{
    "success": true,
    "statusCode": 200,
    "message": "success",
    "data": {
        "id": "68bfeb90aa5fe513b07a3e01",
        "parentId": null,
        "status": "found",
        "reason": null,
        "dataValidation": false,
        "selfieValidation": false,
        "pin": "A009274632R",
        "pinCurrentStatus": "Registered",
        "effectiveFromDate": "2013-12-31",
        "effectiveToDate": null,
        "itaxStatus": "iPage Updated",
        "obligationName": "Income Tax - Resident Individual",
        "pinStatus": "Active",
        "taxpayerName": "Remmy Simiyu Wanjala",
        "idNumber": "A009274632R",
        "isConsent": true,
        "businessId": "65114a8ded14f6cf554e6b34",
        "type": "kePinCheck",
        "allValidationPassed": true,
        "requestedAt": "2025-09-09T08:55:44.963Z",
        "requestedById": "65114a8eed14f64d2d4e6b35",
        "country": "KE",
        "createdAt": "2025-09-09T08:55:44.971Z",
        "lastModifiedAt": "2025-09-09T08:55:44.971Z",
        "adverseMediaReport": null,
        "amlReport": null,
        "metadata": {},
        "requestedBy": {
            "firstName": "API",
            "lastName": "User",
            "middleName": "",
            "id": "65114a8eed14f64d2d4e6b35"
        }
    },
    "links": []
}
```

{% endtab %}
{% endtabs %}

### <mark style="color:purple;">Tax PIN Verification Not Found Sample</mark>

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

{% tabs %}
{% tab title="Not Found Sample Response" %}

```json
{
    "success": true,
    "statusCode": 200,
    "message": "success",
    "data": {
        "id": "68bfee49aa5fe513b07a3e19",
        "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,
        "idNumber": "A0092746321",
        "isConsent": true,
        "businessId": "65114a8ded14f6cf554e6b34",
        "type": "kePinCheck",
        "allValidationPassed": false,
        "requestedAt": "2025-09-09T09:07:21.743Z",
        "requestedById": "65114a8eed14f64d2d4e6b35",
        "country": "KE",
        "createdAt": "2025-09-09T09:07:21.752Z",
        "lastModifiedAt": "2025-09-09T09:07:21.752Z",
        "adverseMediaReport": null,
        "amlReport": null,
        "metadata": {},
        "requestedBy": {
            "firstName": "API",
            "lastName": "User",
            "middleName": "",
            "id": "65114a8eed14f64d2d4e6b35"
        }
    },
    "links": []
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Error Response" %}

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

{% endtab %}
{% endtabs %}