Download TIS

Endpoint Overview

POST /api/v1/itr/download-tis

Description

The Download Taxpayer Information Summary (TIS) API enables developers to programmatically retrieve comprehensive taxpayer information from the Income Tax Department of India. This endpoint provides access to the Taxpayer Information Summary document, which contains detailed financial data, personal information, and transaction summaries for a specific PAN holder during a given financial year.

The TIS document includes critical taxpayer data such as personal details (PAN, Aadhaar, contact information), dividend income statements, securities transactions, and other Statement of Financial Transactions (SFT) information. This API streamlines the process of accessing tax-related information that would otherwise require manual portal access and document downloads.

Key Benefits

Automated Tax Data Retrieval: Eliminate manual downloads from the Income Tax portal by programmatically fetching TIS documents

Comprehensive Financial Insights: Access detailed transaction data including dividends, securities purchases/sales, and SFT information

Structured Data Format: Receive taxpayer information in a well-organized JSON structure for easy integration and processing

Real-time Access: Retrieve up-to-date taxpayer information instantly for verification, analysis, or compliance purposes

Use Cases

Financial Services

Fintech & Digital Lending

Tax & Compliance

Loan Underwriting: Verify applicant income sources and financial transactions during credit assessment processes

Wealth Management: Analyze client investment activities and dividend income for portfolio management

Financial Planning: Access comprehensive tax data to provide personalized financial advisory services

Risk Assessment: Evaluate customer financial profiles for risk-based lending decisions

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	Bearer token for API 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 for the client/taxpayer whose TIS data needs to be retrieved. Format: `itr_{alphanumeric_string}`

Example Request

{
    "client_id": "itr_JkrkByMtlRdWdsyne"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container object for all taxpayer information
data.client_id	String	Unique client identifier used in the request
data.pan_no	String	Permanent Account Number (PAN) of the taxpayer
data.tis_data	Object	Complete Taxpayer Information Summary data
data.tis_data.document_name	String	Name of the document (Taxpayer Information Summary)
data.tis_data.financial_year	String	Financial year for which the TIS is generated (e.g., "2020-21")
data.tis_data.general_information	Array	Array containing taxpayer's personal and contact details
data.tis_data.general_information[].permanent_account_number__pan_	String	PAN of the assessee
data.tis_data.general_information[].aadhaar_number	String	Masked Aadhaar number (format: XXXX XXXX followed by last 4 digits)
data.tis_data.general_information[].name_of_assessee	String	Full name of the taxpayer
data.tis_data.general_information[].date_of_birth	String	Date of birth in DD/MM/YYYY format
data.tis_data.general_information[].mobile_number	String	Registered mobile number
data.tis_data.general_information[].e_mail_address	String	Registered email address
data.tis_data.general_information[].address	String	Complete registered address
data.tis_data.sections	Array	Array of sections containing detailed financial transaction information
data.tis_data.sections[].title	String/Null	Section title if applicable
data.tis_data.sections[].sub_section	Array	Array of subsections
data.tis_data.sections[].elements	Array	Array of elements containing transaction details and summaries
data.tis_data.sections[].elements[].title	String/Null	Element title (e.g., document name, annexure name)
data.tis_data.sections[].elements[].summary	Array	Array of summary entries for financial transactions
data.tis_data.sections[].elements[].summary[].part	String	Type of financial statement (e.g., "SFT" for Statement of Financial Transactions)
data.tis_data.sections[].elements[].summary[].information_description	String	Description of the financial transaction (e.g., "Dividend income (SFT-015)")
data.tis_data.sections[].elements[].summary[].information_source	String	Source entity that reported the information (includes name and identification)
data.tis_data.sections[].elements[].summary[].amount_description	String	Description of the amount field
data.tis_data.sections[].elements[].summary[].reported_by_source	String	Amount reported by the source entity
data.tis_data.sections[].elements[].summary[].processed_by_system	String	Amount processed by the Income Tax system
data.tis_data.sections[].elements[].summary[].accepted_by_taxpayer	String	Amount accepted/confirmed by the taxpayer
data.tis_data.sections[].elements[].details	Array	Array for detailed information (if applicable)
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates whether the request was successful
message	String	Human-readable message describing the result
message_code	String	Machine-readable message code for programmatic handling

Example Successful Response

{
    "data": {
        "client_id": "itr_JkrkByMtlRdWdsyne",
        "pan_no": "ABCPD1234E",
        "tis_data": {
            "document_name": "Taxpayer Information Summary (TIS)",
            "financial_year": "2020-21",
            "general_information": [
                {
                    "permanent_account_number__pan_": "ABCPN1234E",
                    "aadhaar_number": "XXXX XXXX 3863",
                    "name_of_assessee": "MAYUR VIHAR",
                    "date_of_birth": "02/12/1996",
                    "mobile_number": "9876543210",
                    "e_mail_address": "abc1234@gmail.com",
                    "address": "KALYAN,THANE,421306,MAHARASHTRA"
                }
            ],
            "sections": [
                {
                    "title": null,
                    "sub_section": [],
                    "elements": [
                        {
                            "title": "Taxpayer Information Summary (TIS)",
                            "summary": [],
                            "details": []
                        },
                        {
                            "title": "Annexure to Taxpayer Information Summary (TIS)",
                            "summary": [
                                {
                                    "part": "SFT",
                                    "information_description": "Dividend income (SFT-015)",
                                    "information_source": "FINANCE CORPORATION (AACCI1234C.AN123)",
                                    "amount_description": "Total Dividend amount",
                                    "reported_by_source": "611",
                                    "processed_by_system": "611",
                                    "accepted_by_taxpayer": "611"
                                },
                                {
                                    "part": "SFT",
                                    "information_description": "Dividend income (SFT-015)",
                                    "information_source": "Corporate LIMITED (ABCCI12340L.AZ123)",
                                    "amount_description": "Total Dividend amount",
                                    "reported_by_source": "20",
                                    "processed_by_system": "20",
                                    "accepted_by_taxpayer": "20"
                                }
                            ],
                            "details": []
                        },
                        {
                            "title": null,
                            "summary": [
                                {
                                    "part": "SFT",
                                    "information_description": "Sale of listed equity share (Depository)",
                                    "information_source": "ABC SERVICES(I) LIMITED (AAACC1234AMUMC12345A)",
                                    "amount_description": "Value of consideration",
                                    "reported_by_source": "10,645",
                                    "processed_by_system": "10,645",
                                    "accepted_by_taxpayer": "10,645"
                                }
                            ],
                            "details": []
                        },
                        {
                            "title": null,
                            "summary": [
                                {
                                    "part": "SFT",
                                    "information_description": "Purchase of securities (SFT - 017)",
                                    "information_source": "ABC SERVICES(I) LIMITED (AAACC1234AMUMC12345A)",
                                    "amount_description": "Total purchase amount",
                                    "reported_by_source": "8,149",
                                    "processed_by_system": "8,149",
                                    "accepted_by_taxpayer": "8,149"
                                }
                            ],
                            "details": []
                        }
                    ]
                }
            ]
        }
    },
    "status_code": 200,
    "success": true,
    "message": "AIS downloaded successfully",
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Authentication Error

Data Not Found

Rate Limit Exceeded

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

This error occurs when the provided client_id is malformed or does not exist in the system.

Integration Best Practices

Security Recommendations

Secure Token Storage: Store JWT tokens securely using environment variables or secure vault solutions. Never hardcode tokens in your application code.

Token Refresh Strategy: Implement automatic token refresh mechanisms before expiration to ensure uninterrupted service.

HTTPS Only: Always use HTTPS endpoints to encrypt data in transit and protect sensitive taxpayer information.

Data Encryption: Encrypt TIS data at rest when storing it in your systems, especially PAN, Aadhaar, and personal information.

Access Control: Implement role-based access control (RBAC) to restrict who can access TIS data within your organization.

Audit Logging: Maintain comprehensive logs of all API calls, including timestamps, user identifiers, and client_ids accessed for compliance purposes.

PII Handling: Follow data protection regulations (DPDPA, GDPR) when processing personally identifiable information from TIS responses.

User Experience Guidelines

Consent Collection: Always obtain explicit user consent before fetching their TIS data. Display clear information about what data will be accessed and how it will be used.

Progress Indicators: Show loading states during API calls as TIS data retrieval may take a few seconds.

Error Handling: Provide user-friendly error messages when TIS data cannot be retrieved, with clear next steps for resolution.

Data Presentation: Present TIS information in a readable format, organizing financial transactions by type and source for easy comprehension.

Privacy First: Display sensitive information (PAN, Aadhaar) in masked format by default, with an option to reveal if needed.

Data Freshness: Inform users about the financial year and date of the TIS data being displayed to manage expectations about currency of information.

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

Data Privacy Compliance: This API processes sensitive personal and financial information. Ensure compliance with the Digital Personal Data Protection Act (DPDPA) 2023, India's data protection framework. Obtain explicit consent from taxpayers before accessing their TIS data.

Purpose Limitation: Use TIS data only for the specific purposes disclosed to and consented by the user. Do not repurpose data for secondary uses without additional consent.

Data Retention: Implement appropriate data retention policies. Delete or anonymize TIS data after the business purpose is fulfilled, unless legally required to retain it for longer periods.

Income Tax Act Compliance: Access to taxpayer information must comply with Section 138 of the Income Tax Act, 1961. Ensure you have proper authorization and legitimate business need to access this information.

Third-Party Sharing: Do not share TIS data with third parties without explicit user consent and proper data processing agreements in place.

Audit Trail: Maintain detailed audit logs of all TIS data access for regulatory compliance and potential audits 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' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "itr_JkrkByMtlRdWdsynelta" }'

{ "data": { "client_id": "itr_JkrkByMtlRdWdsyne", "pan_no": "ABCPD1234E", "tis_data": { "document_name": "Taxpayer Information Summary (TIS)", "financial_year": "2020-21", "general_information": [ { "permanent_account_number__pan_": "ABCPN1234E", "aadhaar_number": "XXXX XXXX 3863", "name_of_assessee": "MAYUR VIHAR", "date_of_birth": "02/12/1996", "mobile_number": "9876543210", "e_mail_address": "abc1234@gmail.com", "address": "KALYAN,THANE,421306,MAHARASHTRA" } ], "sections": [ { "title": null, "sub_section": [], "elements": [ { "title": "Taxpayer Information Summary (TIS)", "summary": [], "details": [] }, { "title": "Annexure to Taxpayer Information Summary (TIS)", "summary": [ { "part": "SFT", "information_description": "Dividend income (SFT-015)", "information_source": "FINANCE CORPORATION (AACCI1234C.AN123)", "amount_description": "Total Dividend amount", "reported_by_source": "611", "processed_by_system": "611", "accepted_by_taxpayer": "611" }, { "part": "SFT", "information_description": "Dividend income (SFT-015)", "information_source": "Corporate LIMITED (ABCCI12340L.AZ123)", "amount_description": "Total Dividend amount", "reported_by_source": "20", "processed_by_system": "20", "accepted_by_taxpayer": "20" } ], "details": [] }, { "title": null, "summary": [ { "part": "SFT", "information_description": "Sale of listed equity share (Depository)", "information_source": "ABC SERVICES(I) LIMITED (AAACC1234AMUMC12345A)", "amount_description": "Value of consideration", "reported_by_source": "10,645", "processed_by_system": "10,645", "accepted_by_taxpayer": "10,645" } ], "details": [] }, { "title": null, "summary": [ { "part": "SFT", "information_description": "Purchase of securities (SFT - 017)", "information_source": "ABC SERVICES(I) LIMITED (AAACC1234AMUMC12345A)", "amount_description": "Total purchase amount", "reported_by_source": "8,149", "processed_by_system": "8,149", "accepted_by_taxpayer": "8,149" } ], "details": [] } ] } ] } }, "status_code": 200, "success": true, "message": "AIS downloaded successfully", "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