Download ITR Form

Endpoint Overview

POST /api/v1/itr/download-itr-form

Description

The Download ITR Form API enables developers to programmatically retrieve a pre-signed, downloadable link to a taxpayer's filed Income Tax Return (ITR) form in PDF format. By submitting a unique client identifier, the API fetches all associated filed ITR records — including details such as the filing year, acknowledgement number, filing type, ITR form variant, and filing date — alongside a time-limited, secure download URL hosted on Amazon S3.

This endpoint is particularly valuable in financial and compliance workflows where automated access to verified tax documents is required — eliminating manual retrieval from government portals and enabling seamless integration into document management, loan processing, and onboarding pipelines.

Key Benefits

Instant Document Access: Retrieve secure, time-limited download links to filed ITR PDF forms in a single API call, removing the need for manual portal logins.

Rich Filing Metadata: Each response includes comprehensive filing details such as acknowledgement number, ITR form type, filing section, filing year, and the entity that filed the return.

Multi-Record Support: The API returns all filed ITR records associated with a PAN, enabling full filing history retrieval in one request.

Secure Pre-Signed URLs: Download links are AWS S3 pre-signed URLs with expiry, ensuring controlled and secure document access.

Use Cases

Banking & Lending

Insurance

HR & Payroll

Automatically fetch ITR forms during loan application processing to verify borrower income without manual document submission.

Streamline credit underwriting by programmatically validating tax filings against declared income figures.

Enable instant income verification for personal loans, home loans, and business credit lines.

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.app

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

Request Parameters

Request Headers

Header	Required	Description
`Authorization`	Yes	JWT Bearer token for the target environment. Format: `Bearer <token>`
`Content-Type`	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
`client_id`	String	Yes	The unique client identifier for the ITR record. This is generated when the ITR data is initially fetched or stored via Surepass. Follows the format `itr_<alphanumeric>`.

Example Request

{
    "client_id": "itr_qKctszfxrMshYrznYuRP"
}

Process Response

Response Parameters

Parameter	Type	Description
`data`	Object	Top-level wrapper containing the ITR filing data.
`data.client_id`	String	The unique client identifier associated with the request, in the format `itr_<alphanumeric>`.
`data.pan_no`	String	The Permanent Account Number (PAN) of the taxpayer.
`data.filed_itr_form`	Array	List of all filed ITR records associated with the PAN. Each element represents one filed return.
`data.filed_itr_form[].download_link`	String	A time-limited, pre-signed AWS S3 URL to download the ITR form as a PDF. This URL expires after a short duration (typically 600 seconds).
`data.filed_itr_form[].pan_no`	String	The PAN number associated with this specific ITR filing.
`data.filed_itr_form[].filing_year`	String	The assessment year for which the ITR was filed, in the format `YYYY-YYYY` (e.g., `2025-2026`).
`data.filed_itr_form[].acknowledgement_no`	String	The unique acknowledgement number issued by the Income Tax Department upon successful filing.
`data.filed_itr_form[].filing_type`	String	Indicates whether the return is an `Original` filing or a `Revised` filing.
`data.filed_itr_form[].filing_section`	String	The section of the Income Tax Act under which the return was filed (e.g., `139(1)` for returns filed before the due date).
`data.filed_itr_form[].filled_by`	String	Indicates who filed the return — `Self` if filed by the taxpayer, or the name/type of the intermediary (e.g., tax professional).
`data.filed_itr_form[].itr_form`	String	The specific ITR form variant used for filing (e.g., `ITR-1`, `ITR-2`, `ITR-4`).
`data.filed_itr_form[].filing_date`	String	The date on which the return was filed, in `YYYY-MM-DD` format.
`data.filed_itr_form[].status`	String	Processing status of the download for this record. `success` indicates the download link was generated successfully.
`data.skip_failure`	Boolean	If `true`, records that failed to process are skipped and the rest are returned. If `false`, any failure will affect the overall response.
`status_code`	Integer	HTTP-equivalent status code for the API operation. `200` indicates success.
`success`	Boolean	`true` if the API call was processed successfully; `false` otherwise.
`message`	String / null	A human-readable message describing the result. `null` on success.
`message_code`	String	A machine-readable response code (e.g., `success`, `error`).

Example Successful Response

{
    "data": {
        "client_id": "itr_rsRgMyiDkbyuPFoxorTA",
        "pan_no": "ABCPD1234A",
        "filed_itr_form": [
            {
                "download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_rsRgMyiDkbyuPFoxorTA/ARJPV5762A/933762040110925_itr_form-2026-05-27-053642007309.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20260527%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20260527T053703Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=9c60d3a32d2d1d5591c50a6cd2a89615ac73b3eac26f3fc5c9d4859f0090a3d4",
                "pan_no": "ABCPD1234A",
                "filing_year": "2025-2026",
                "acknowledgement_no": "261315954613480",
                "filing_type": "Original",
                "filing_section": "139(1)",
                "filled_by": "Self",
                "itr_form": "ITR-2",
                "filing_date": "2025-09-11",
                "status": "success"
            }
        ],
        "skip_failure": false
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Unauthorized (401)

Invalid Client ID (400)

Server Error (500)

{
    "data": null,
    "status_code": 401,
    "success": false,
    "message": "Authentication credentials were not provided or are invalid.",
    "message_code": "unauthorized"
}

Returned when the Authorization header is missing, malformed, or contains an expired/invalid JWT token. Ensure you are using the correct Bearer token for the target environment (sandbox or production).

Integration Best Practices

Security Recommendations

Treat pre-signed URLs as sensitive: The download_link returned in each filed_itr_form record is a time-limited pre-signed S3 URL (valid for ~600 seconds). Download and store the PDF securely before the URL expires. Never expose these URLs in client-side code or logs.

Use environment-specific tokens: Always use separate JWT tokens for sandbox and production environments. Never use a production token in testing workflows.

Rotate credentials regularly: Periodically regenerate your JWT tokens and update them in your integration to reduce the risk of unauthorized access.

Transmit over HTTPS only: Always call this API over HTTPS. Never transmit the Bearer token or client_id over unencrypted connections.

Restrict token scope: Where possible, limit the API key permissions to only the endpoints required by your integration.

User Experience Guidelines

Handle URL expiry gracefully: Since download_link URLs expire in approximately 600 seconds, initiate the PDF download immediately after receiving the response. If expiry is detected (e.g., HTTP 403 on download), re-call this endpoint to obtain a fresh link.

Display filing metadata to users: Surface the filing_year, itr_form, filing_date, and acknowledgement_no fields to give users clear context about which ITR document they are viewing or downloading.

Handle multiple filings: A taxpayer may have multiple entries in filed_itr_form. Present these as a list ordered by filing_year and filing_date descending, so the most recent filing is most prominent.

Show appropriate loading states: ITR form retrieval may take a moment. Display a loading indicator while the API call is in progress to avoid repeated user submissions.

Communicate skip_failure outcomes: If skip_failure is true and some records are missing, inform users that partial results are shown and advise them to retry or contact support for the missing filings.

Code Samples

cURL

Python

Node.js

Related APIs

Fetch ITR Data — Retrieves the raw Income Tax Return data for a taxpayer using their PAN and consent. This is typically called before the Download ITR Form endpoint to generate the client_id.

ITR Compliance Check — Validates whether a taxpayer's filed returns are compliant with current Income Tax regulations, useful in risk assessment workflows.

PAN Verification — Verifies the validity of a PAN number and fetches associated taxpayer details. Often used as a prerequisite step before ITR-related operations.

Form 26AS Fetch — Retrieves the Annual Information Statement (AIS) / Form 26AS for a given PAN, which complements ITR filing data with TDS, TCS, and other financial transaction records.

Compliance and Legal Considerations

Taxpayer Consent: This API accesses sensitive personal tax information. Ensure that explicit, informed consent has been obtained from the taxpayer before initiating any ITR data fetch or download request, in compliance with applicable data protection regulations.

Data Localisation: ITR documents contain sensitive financial data subject to Indian data protection laws, including the Digital Personal Data Protection Act, 2023 (DPDPA). Ensure all fetched documents are stored and processed within compliant infrastructure.

Retention Policies: Downloaded ITR PDFs must be retained only for as long as is necessary for the stated business purpose. Implement documented data retention and deletion policies.

Audit Trails: Maintain logs of all API calls made under this endpoint, including the client_id, timestamp, and the initiating user or system, to support compliance audits.

No Unauthorised Redistribution: ITR documents retrieved via this API must not be redistributed, shared, or used for any purpose beyond that for which the taxpayer's consent was obtained.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location 'https://kyc-api.surepass.app/api/v1/itr/download-itr-form' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "client_id": "itr_qKctszfxrMshYrznYuRP" }'

{ "data": { "client_id": "itr_rsRgMyiDkbyuPFoxorTA", "pan_no": "ABCPD1234A", "filed_itr_form": [ { "download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_rsRgMyiDkbyuPFoxorTA/ARJPV5762A/933762040110925_itr_form-2026-05-27-053642007309.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20260527%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20260527T053703Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=9c60d3a32d2d1d5591c50a6cd2a89615ac73b3eac26f3fc5c9d4859f0090a3d4", "pan_no": "ABCPD1234A", "filing_year": "2025-2026", "acknowledgement_no": "261315954613480", "filing_type": "Original", "filing_section": "139(1)", "filled_by": "Self", "itr_form": "ITR-2", "filing_date": "2025-09-11", "status": "success" } ], "skip_failure": false }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

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