# ITR Verification

The ITR-V API allows users to securely retrieve Income Tax Return Verification details, confirming successful filing and providing essential taxpayer information. 

## ITR Verification

<mark style="color:green;">`POST`</mark> `https://secctrl.tutelar.io/api/v1/services/business_profile/itr_verification`

#### Sample Request Body

<table><thead><tr><th width="167">Body</th><th width="148">Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>user_name</td><td>string</td><td>Yes</td><td>Username of the itr portal.<br>Typically it the pan of the user</td></tr><tr><td>password</td><td>string</td><td>Yes</td><td>Password of the portal</td></tr><tr><td>range</td><td>number</td><td>Yes</td><td>The number of years for which<br>data is being requested</td></tr></tbody></table>

#### Sample Post Parameters

```json
{
    "user_name": "ABCDE1234F",
    "password": "Test@123",
    "range": 1
}
```

{% tabs %}
{% tab title="200: Success Response" %}

```json
{
    "success": true,
    "code": 200,
    "message": "The request has been successfully completed.",
    "reference_id": "372b45f0-23d1-434b-b708-33510e4e4d6c",
    "status": "completed",
    "result": {
        "message": "1 year ITR V available in the last 1 years",
        "itr_result": [
            {
                "pan_number": "EVXPD2019C",
                "filing_year": "2024-2025",
                "acknowledgement_number": "219853550300625",
                "filing_type": "Original",
                "assessment_pdf": "http://3.108.106.182:8000/image-pub/kyc/TUTWEBK00341/itrAssesmentDocuments/itr_assesment_file_1771942044796-1771942044811.pdf"
            }
        ]
    },
    "requested_at": "2026-02-24T14:07:13.087Z",
    "completed_at": "2026-02-24T14:07:25.911Z"
}
```

{% endtab %}

{% tab title="400: Validation Error Response" %}

```json
{
    "success": false,
    "code": 400,
    "message": "User Name should not be empty",
    "error": {
        "message": "User Name should not be empty",
        "field": "user_name",
        "code": "BAD_REQUEST"
    }
}

{
    "success": false,
    "code": 400,
    "message": "Password Should not empty",
    "error": {
        "message": "Password Should not empty",
        "field": "password",
        "code": "BAD_REQUEST"
    }
}

{
    "success": false,
    "code": 400,
    "message": "Range must be a number between 1 and 7",
    "error": {
        "message": "Range must be a number between 1 and 7",
        "field": "range",
        "code": "BAD_REQUEST"
    }
}
```

{% endtab %}

{% tab title="200 : In progress" %}

```json
{
    "success": true,
    "code": 200,
    "message": "The request is being processed. Please wait for completion.",
    "reference_id": "91084d90-4468-43c8-b537-cd7a69d2e2b1",
    "status": "in_progress",
    "requested_at": "2026-02-24T14:40:18.115Z"
}
```

{% endtab %}

{% tab title="200: Failure Response" %}

```json
{
    "success": true,
    "code": 200,
    "message": "The request could not be completed due to an error.",
    "reference_id": "91084d90-4468-43c8-b537-cd7a69d2e2b1",
    "status": "failed",
    "error": {
        "message": "Incorrect credentials, cannot login. Please try again",
        "code": "ERROR"
    },
    "requested_at": "2026-02-24T14:40:18.115Z",
    "completed_at": "2026-02-24T14:40:35.633Z"
}
```

{% endtab %}
{% endtabs %}

#### Check Document Status

## Get document details

<mark style="color:blue;">`GET`</mark> `https://secctrl.tutelar.io/api/v1/services/business_profile/itr_verification`

### Query parameters description is given below,

<table><thead><tr><th width="197">Query Parameter </th><th width="139">Type</th><th>Is  Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>reference_id </td><td>String </td><td>Yes </td><td>Document reference id</td></tr></tbody></table>

{% tabs %}
{% tab title="200: Success Response" %}

```json
{
    "success": true,
    "code": 200,
    "message": "The request has been successfully completed.",
    "reference_id": "372b45f0-23d1-434b-b708-33510e4e4d6c",
    "status": "completed",
    "result": {
        "message": "1 year ITR V available in the last 1 years",
        "itr_result": [
            {
                "pan_number": "EVXPD2019C",
                "filing_year": "2024-2025",
                "acknowledgement_number": "219853550300625",
                "filing_type": "Original",
                "assessment_pdf": "http://3.108.106.182:8000/image-pub/kyc/TUTWEBK00341/itrAssesmentDocuments/itr_assesment_file_1771942044796-1771942044811.pdf"
            }
        ]
    },
    "requested_at": "2026-02-24T14:07:13.087Z",
    "completed_at": "2026-02-24T14:07:25.911Z"
}
```

{% endtab %}

{% tab title="200: Inprogress Response" %}

```json
{
    "success": true,
    "code": 200,
    "message": "The request is being processed. Please wait for completion.",
    "reference_id": "91084d90-4468-43c8-b537-cd7a69d2e2b1",
    "status": "in_progress",
    "requested_at": "2026-02-24T14:40:18.115Z"
}
```

{% endtab %}

{% tab title="200: Failure Response" %}

```json
{
    "success": true,
    "code": 200,
    "message": "The request could not be completed due to an error.",
    "reference_id": "91084d90-4468-43c8-b537-cd7a69d2e2b1",
    "status": "failed",
    "error": {
        "message": "Incorrect credentials, cannot login. Please try again",
        "code": "ERROR"
    },
    "requested_at": "2026-02-24T14:40:18.115Z",
    "completed_at": "2026-02-24T14:40:35.633Z"
}
```

{% endtab %}
{% endtabs %}