Download AIS V2

Endpoint Overview

POST /api/v1/itr/download-ais-v2

Description

This endpoint allows you to download Account Information Service (AIS) data associated with a client's Income Tax Returns (ITR). AIS data contains comprehensive financial information reported to tax authorities, including income from various sources, tax deductions, and other financial transactions. This API initiates the download process and provides status tracking for large AIS files.

Key Benefits

Retrieve official AIS data directly from tax authority sources

Access comprehensive financial information for verification and analysis

Streamline tax filing processes with automated data retrieval

Track status of large AIS file downloads with a simple polling mechanism

Use Cases

Financial Services

Tax Preparation

Accounting

Verify income claims during loan application processing

Automate financial profile creation for wealth management clients

Validate customer-provided financial information for credit assessment

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 Client ID obtained from Create Client endpoint
financial_year	String	Yes	Financial year in "YYYY-YY" format (e.g., "2022-23")

Example Request

{
    "client_id": "itr_zPFdvKzxGoZEOmJuPZfc",
    "financial_year": "2022-23"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the response data
data.client_id	String	Unique Client ID
data.pan_no	String	PAN (Permanent Account Number) of the client
data.ais_file	String	The file containing AIS data (empty if status is pending)
data.file_type	String	Type of the file (JSON/PDF, empty if status is pending)
data.status	String	Current status of the AIS download (pending/completed)
data.financial_year	String	Financial year associated with the data (e.g., "2022-23")
status_code	Integer	HTTP status code
success	Boolean	Indicates if the request was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "client_id": "itr_NbbjQVLknmgpagZXpxta",
        "pan_no": "EOHPK1234E",
        "ais_file": "",
        "file_type": "",
        "status": "pending",
        "financial_year": "2022-23"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Invalid Financial Year

Authentication Error

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

The client_id provided does not exist or is not valid.

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

Use HTTPS for all API communications to ensure data encryption in transit

Implement token refresh mechanisms to handle token expiration gracefully

User Experience Guidelines

Implement a polling mechanism to check the status of large AIS downloads

Display appropriate loading indicators during the pending state

Provide clear error messages to users when issues occur

Cache successful responses to reduce redundant API calls

Code Samples

cURL

Python

Node.js

Related APIs

Get AIS: Retrieve the status and content of a previously initiated AIS download

Create Client: Generate a unique client ID required for AIS download

Get ITR Status: Check the status of Income Tax Return filing

Download Form 26AS: Download Tax Credit Statement (Form 26AS)

Compliance and Legal Considerations

The AIS data contains sensitive financial information protected under data privacy laws. Ensure you have proper consent from the client before accessing their data. Store and process this information in compliance with applicable data protection regulations. The use of this API may be subject to terms and conditions set by tax authorities.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/itr/download-ais-v2' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "itr_zPFdvKzxGoZEOmJuPZfc", "financial_year": "2022-23" }'

{ "data": { "client_id": "itr_NbbjQVLknmgpagZXpxta", "pan_no": "EOHPK1234E", "ais_file": "", "file_type": "", "status": "pending", "financial_year": "2022-23" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Download AIS V2

Download AIS V2#

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 AIS V2

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples