Get AIS

Endpoint Overview

POST /api/v1/itr/get-ais

Description

This API allows you to check the status of large Annual Information Statement (AIS) requests that were previously marked as pending in the "Download AIS V2" endpoint. It retrieves the current status of AIS data processing and provides access to the completed AIS file when available.

Key Benefits

Track the processing status of large AIS requests

Retrieve completed AIS files without reinitiating the request

Access both PDF and JSON formats of AIS data

Seamlessly integrate with your existing ITR processing workflows

Use Cases

Financial Services

Tax Preparation

Wealth Management

Automate tax filing processes by retrieving AIS data for clients

Integrate AIS data into financial planning and advisory services

Verify client income and tax information for 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 authentication using JWT
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
client_id	String	Yes	Unique Client ID obtained from the "Download AIS V2" 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 AIS data
data.client_id	String	Unique Client ID
data.pan_no	String	PAN (Permanent Account Number) of the client
data.ais_file	String	URL pointing to the AIS data file
data.file_type	String	Type of the file (JSON or PDF)
data.status	String	Current status of the AIS data (pending or 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	Response message
message_code	String	Code representing the response message

Example Successful Response

{
    "data": {
        "client_id": "itr_NbbjQVLknmgpagZXpxta",
        "pan_no": "EOHPK1234E",
        "ais_file": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_NbbjQVLknmgpagZXpxta/EOHP1234E/1804202420004784-2024-04-18-150908417544.pdf?X-Amz-Algorith",
        "file_type": "pdf",
        "status": "completed",
        "financial_year": "2022-23"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Authentication Error

Invalid Financial Year

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

This error occurs when the provided client_id doesn't exist or is invalid.

Integration Best Practices

Security Recommendations

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

Implement proper error handling to manage authentication failures

Set up automated token refresh mechanisms to handle token expiration

Use HTTPS for all API communications to ensure data encryption

User Experience Guidelines

Implement a polling mechanism for pending requests with appropriate intervals

Display meaningful progress indicators while waiting for AIS data to be processed

Provide clear error messages to users when AIS retrieval fails

Cache AIS data appropriately to minimize redundant API calls

Code Samples

cURL

Python

Node.js

Related APIs

Download AIS V2: Initiates AIS data retrieval and returns immediate results or a pending status

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

Get Form 26AS: Retrieves Tax Credit Statement (Form 26AS) for a PAN

Compliance and Legal Considerations

The AIS data contains sensitive financial information protected under various privacy laws. Ensure you have proper consent from users before accessing their AIS data. Store and process this data in compliance with applicable data protection regulations. The AIS data should only be used for authorized purposes as agreed with the end user.

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/get-ais' \ --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": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_NbbjQVLknmgpagZXpxta/EOHP1234E/1804202420004784-2024-04-18-150908417544.pdf?X-Amz-Algorith", "file_type": "pdf", "status": "completed", "financial_year": "2022-23" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Get AIS

Get AIS#

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

Get AIS

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples