Download ITR V

Endpoint Overview

POST /api/v1/itr/download-itr-v

Description

This API endpoint retrieves the complete history of filed Income Tax Returns (ITR) for a specified PAN number. It provides detailed information about each filing, including the financial year, acknowledgment number, filing type (Original/Revised), and most importantly, a secure download link for the ITR-V (Income Tax Return-Verification) document. The ITR-V is an official acknowledgment receipt issued by the Income Tax Department after successful e-filing of an income tax return.

Key Benefits

Retrieve multiple years of ITR filing history with a single API call

Access direct, secure download links for ITR-V documents

Verify filing status and obtain official acknowledgment numbers

Streamline tax compliance verification processes

Use Cases

Financial Services

Accounting & Tax

HR & Employment

Loan processing: Verify income declarations with official ITR documents

Credit assessment: Analyze financial stability through tax filing history

Wealth management: Maintain comprehensive client tax records

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token authentication using JWT
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
client_id	String	Yes	Unique identifier for the client, obtained from the Create Client endpoint

Example Request

{
    "client_id": "itr_yvVgzoTdmctBsvQfuFRE"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the response data
data.client_id	String	Unique identifier for the API request
data.pan_no	String	PAN (Permanent Account Number) of the client
data.filed_itrv	Array	List of filed ITR documents and their details
data.filed_itrv[].download_link	String	Secure URL to download the ITR-V document (valid for limited time)
data.filed_itrv[].pan_no	String	PAN number associated with the ITR filing
data.filed_itrv[].filing_year	String	Financial year for which the ITR was filed (format: YYYY-YYYY)
data.filed_itrv[].acknowledgement_no	String	Unique acknowledgement number issued by the Income Tax Department
data.filed_itrv[].filing_type	String	Type of filing (Original or Revised)
data.filed_itrv[].status	String	Status of the filing (if applicable)
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the API request was successful
message	String	Additional information or error message (null if successful)
message_code	String	Code indicating the status of the request

Example Successful Response

{
    "data": {
        "client_id": "itr_yvVgzoTdmctBsvQfuFRE",
        "pan_no": "AZXAS0122L",
        "filed_itrv": [
            {
                "download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_yvVgzoTdmctBsvQfjUCk/AZXPS0133L/535617900290624_itrv-2025-01-17-105501029113.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5FYWPQJEB%2F20250117%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20250117T105804Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=19d709ff5e021e4a7fe8c503d8e22f8ffe575b2e10",
                "pan_no": "AZXAS0122L",
                "filing_year": "2023-2024",
                "acknowledgement_no": "535617900290555",
                "filing_type": "Original",
                "status": ""
            },
            {
                "download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_yvVgzoTdmctBsvQfjUCk/AZXPS0133L/285239520230623_itrv-2025-01-17-105501831611.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5FYWPQJEB%2F20250117%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20250117T105804Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=1388632435be846d8f45b696a128444179e9e17e",
                "pan_no": "AZXAS0122L",
                "filing_year": "2022-2023",
                "acknowledgement_no": "285239520230554",
                "filing_type": "Original",
                "status": ""
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Authentication Error

No ITR Records

{
    "data": null,
    "status_code": 400,
    "success": false,
    "message": "Invalid client_id provided",
    "message_code": "invalid_client_id"
}

This error occurs when the provided client_id is invalid, doesn't exist, or is in an incorrect format.

Integration Best Practices

Security Recommendations

Store the JWT token securely and never expose it in client-side code

Download links are temporary and expire after a short period (typically 10 minutes) - implement immediate download after retrieval

Implement proper error handling for expired download links

Store downloaded ITR-V documents in secure, encrypted storage with appropriate access controls

User Experience Guidelines

Implement a caching mechanism to avoid repeated API calls for the same client_id

Display filing years in a user-friendly format (e.g., "FY 2023-24" instead of "2023-2024")

Provide clear download buttons with appropriate labels including the filing year

Implement progress indicators during document download

Code Samples

cURL

Python

Node.js

Related APIs

Create Client API: Creates a new client record and returns a client_id

ITR Status API: Checks the status of ITR filing for a given PAN

ITR Filing API: Initiates the filing of an Income Tax Return

ITR Verification API: Verifies the authenticity of an ITR document

Compliance and Legal Considerations

The ITR-V documents contain sensitive financial information and are subject to data protection regulations. Ensure compliance with applicable privacy laws such as the Personal Data Protection Bill in India. Organizations must obtain explicit consent from individuals before accessing their tax information and implement appropriate security measures to protect this data. The downloaded documents should only be used for legitimate business purposes as specified in your terms of service.

{ "data": { "client_id": "itr_yvVgzoTdmctBsvQfuFRE", "pan_no": "AZXAS0122L", "filed_itrv": [ { "download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_yvVgzoTdmctBsvQfjUCk/AZXPS0133L/535617900290624_itrv-2025-01-17-105501029113.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5FYWPQJEB%2F20250117%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20250117T105804Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=19d709ff5e021e4a7fe8c503d8e22f8ffe575b2e10", "pan_no": "AZXAS0122L", "filing_year": "2023-2024", "acknowledgement_no": "535617900290555", "filing_type": "Original", "status": "" }, { "download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_yvVgzoTdmctBsvQfjUCk/AZXPS0133L/285239520230623_itrv-2025-01-17-105501831611.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5FYWPQJEB%2F20250117%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20250117T105804Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=1388632435be846d8f45b696a128444179e9e17e", "pan_no": "AZXAS0122L", "filing_year": "2022-2023", "acknowledgement_no": "285239520230554", "filing_type": "Original", "status": "" } ] }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Download ITR V

Download ITR V#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Download ITR V

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples