Download 26AS

Endpoint Overview

POST /api/v1/itr/download-26as

Description

This API endpoint allows you to download Form 26AS, which is an annual tax statement issued by the Income Tax Department of India. It contains details of tax deducted at source (TDS), tax collected at source (TCS), and other tax-related information for a specific PAN number. By providing a unique client ID, you can retrieve Form 26AS for multiple assessment years in a single request.

Key Benefits

Retrieve Form 26AS data for multiple assessment years in a single API call

Obtain direct download links for each year's tax statement

Verify tax deductions and credits reported to the tax department

Streamline tax filing processes by automating Form 26AS retrieval

Use Cases

Financial Services

Tax Preparation

Corporate HR

Automate tax statement retrieval for wealth management clients

Integrate Form 26AS data into tax planning software

Verify TDS claims during loan processing

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 for authentication. Format: `Bearer {JWT_TOKEN}`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
client_id	String	Yes	Unique identifier of the client for whom Form 26AS is being requested

Example Request

{
    "client_id": "itr_usrydGkBEqjfdsQMguMb"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the main response data
data.client_id	String	Unique identifier of the client
data.pan_no	String	PAN Number of the client
data.tds	Array	List of TDS details for different assessment years
data.tds[].tds_id	String	TDS identifier as per TDS details
data.tds[].assessment_year	String	Assessment year for the TDS details
data.tds[].download_link	String	Temporary URL to download the Form 26AS (valid for a limited time)
data.tds[].message	String	Status message for this specific TDS record
data.tds[].message_code	String	Status code for this specific TDS record
status_code	Number	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Overall status message of the response
message_code	String	Overall status code of the response

Example Successful Response

{
    "data": {
        "client_id": "itr_LkksSlHrooCssgibbaol",
        "pan_no": "AAPPL2222A",
        "tds": [
            {
                "tds_id": "250",
                "assessment_year": "2024-2025",
                "download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr_26as/itr_LkksSlHrooCssgibbaol/AAPPL2222A/18689f6f-d18f-4a3b-8eb4-fa3876bbef23_26as-2023-07-28-113743435492.json?X-AmzAlgo-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20230728T113744Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=42d9589e99d410c028007b698d3c4bb33df6c11faab342cb4fd181ee66bb28f1",
                "message": "Success",
                "message_code": "success"
            },
            {
                "tds_id": "946",
                "assessment_year": "2023-2024",
                "download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr_26as/itr_LkksSlHrooCssgibbaol/AAPPL2222A/c310f4a1-87cf-42a3-a453-cd879475d0e2_26as-2023-07-28-113743585506.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_reqX-Amz-Signature=b1bbd7819a93992c263c4a94e2dec3a982c59147e9404ab9697fb499aa68dbfd",
                "message": "Success",
                "message_code": "success"
            },
            {
                "tds_id": "7050",
                "assessment_year": "2022-2023",
                "download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr_26as/itr_LkksSlHrooCssgibbaol/AAPPL2222A/2f132439-5c3b-4146-95f4-5f75e0b360f3_26as-2023-07-28-113743696702.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F202307X-Amz-SignedHeaders=host&X-Amz-Signature=ee7ba63217eb30553f5cf74256c5ebd243066cb78ef4e605ee5b357630b5aa56",
                "message": "Success",
                "message_code": "success"
            },
            {
                "tds_id": "243",
                "assessment_year": "2021-2022",
                "download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr_26as/itr_LkksSlHrooCssgibbaol/AAPPL2222A/61f3f3a1-5c11-4be8-98d6-52855b8d7ab7_26as-2023-07-28-113743814937.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_requestad7594dbf3cf147ca902dee132359ae78fc3579118556bb30fc3b987d603613",
                "message": "Success",
                "message_code": "success"
            },
            {
                "tds_id": "274",
                "assessment_year": "2020-2021",
                "download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr_26as/itr_LkksSlHrooCssgibbaol/AAPPL2222A/02499fab-1029-4713-b494-f06f29c1966f_26as-2023-07-28-113743927128.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_reqe11ed361bb3454f3ecb52e5851765d713aa1be2b149ad67ec8e51203ea9d259",
                "message": "Success",
                "message_code": "success"
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Authentication Error

Service Unavailable

{
    "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 or does not exist in the system.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement proper error handling to avoid exposing sensitive information

Download links are temporary and expire quickly - process them immediately after retrieval

Implement proper data retention policies for downloaded Form 26AS data

Ensure compliance with data protection regulations when storing tax information

User Experience Guidelines

Implement proper loading indicators while fetching Form 26AS data

Provide clear error messages to users when download fails

Allow users to select which assessment years they want to download

Implement retry mechanisms for failed downloads

Consider implementing a caching mechanism to avoid redundant API calls

Code Samples

cURL

Python

Node.js

:::

{ "data": { "client_id": "itr_LkksSlHrooCssgibbaol", "pan_no": "AAPPL2222A", "tds": [ { "tds_id": "250", "assessment_year": "2024-2025", "download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr_26as/itr_LkksSlHrooCssgibbaol/AAPPL2222A/18689f6f-d18f-4a3b-8eb4-fa3876bbef23_26as-2023-07-28-113743435492.json?X-AmzAlgo-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20230728T113744Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=42d9589e99d410c028007b698d3c4bb33df6c11faab342cb4fd181ee66bb28f1", "message": "Success", "message_code": "success" }, { "tds_id": "946", "assessment_year": "2023-2024", "download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr_26as/itr_LkksSlHrooCssgibbaol/AAPPL2222A/c310f4a1-87cf-42a3-a453-cd879475d0e2_26as-2023-07-28-113743585506.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_reqX-Amz-Signature=b1bbd7819a93992c263c4a94e2dec3a982c59147e9404ab9697fb499aa68dbfd", "message": "Success", "message_code": "success" }, { "tds_id": "7050", "assessment_year": "2022-2023", "download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr_26as/itr_LkksSlHrooCssgibbaol/AAPPL2222A/2f132439-5c3b-4146-95f4-5f75e0b360f3_26as-2023-07-28-113743696702.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F202307X-Amz-SignedHeaders=host&X-Amz-Signature=ee7ba63217eb30553f5cf74256c5ebd243066cb78ef4e605ee5b357630b5aa56", "message": "Success", "message_code": "success" }, { "tds_id": "243", "assessment_year": "2021-2022", "download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr_26as/itr_LkksSlHrooCssgibbaol/AAPPL2222A/61f3f3a1-5c11-4be8-98d6-52855b8d7ab7_26as-2023-07-28-113743814937.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_requestad7594dbf3cf147ca902dee132359ae78fc3579118556bb30fc3b987d603613", "message": "Success", "message_code": "success" }, { "tds_id": "274", "assessment_year": "2020-2021", "download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr_26as/itr_LkksSlHrooCssgibbaol/AAPPL2222A/02499fab-1029-4713-b494-f06f29c1966f_26as-2023-07-28-113743927128.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_reqe11ed361bb3454f3ecb52e5851765d713aa1be2b149ad67ec8e51203ea9d259", "message": "Success", "message_code": "success" } ] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Download 26AS

Download 26AS#

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 26AS

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples