TDS Check

Endpoint Overview

POST /api/v1/tan/tds-check

Description

The TDS Check API allows you to retrieve detailed information about Tax Deducted at Source (TDS) returns filed by taxpayers. This endpoint provides comprehensive data about quarterly tax returns, including the number of records, filing status, and other relevant details based on the provided TAN (Tax Deduction Account Number), PAN (Permanent Account Number), financial year, quarter, and type of return.

Key Benefits

Quickly verify if TDS returns have been filed for specific quarters

Access detailed information about filed returns including record counts and remarks

Streamline tax compliance verification processes

Reduce manual effort in tracking TDS filing status

Use Cases

Financial Services

Accounting & Tax

HR & Payroll

Verify TDS compliance for loan applicants before processing applications

Validate client tax compliance as part of KYC processes

Automate tax filing verification for corporate clients

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 (JWT format)
Content-Type	Yes	Application/json

Request Body

Parameter	Type	Required	Description
tan_number	String	Yes	Tax Deduction and Collection Account Number (e.g., "DELS01235E")
pan_number	String	Yes	Permanent Account Number (e.g., "DQABC1234F")
year	String	Yes	Financial year for which the return is filed (e.g., "2020")
quarter	String	Yes	Quarter for which the return is filed (e.g., "Q1", "Q2", "Q3", "Q4")
type_of_return	String	Yes	Type of return filed (e.g., "salary")

Example Request

{
    "tan_number": "DELS01235E",
    "pan_number": "DQABC1234F",
    "year": "2020",
    "quarter": "Q4",
    "type_of_return": "salary"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the response data
data.client_id	String	Unique identifier for the client
data.tan_number	String	Tax Deduction and Collection Account Number
data.pan_number	String	Permanent Account Number
data.year	String	Year for which the return is filed
data.type_of_return	String	Type of return (e.g., salary)
data.quarters	Array	List of quarters for which the return is filed
data.results	Array	List of results for the specified quarters
data.results[].quarter	String	Quarter for the result
data.results[].type_of_return	String	Type of return for the result
data.results[].count_of_records	Integer	Number of records for the result
data.results[].remarks	String	Remarks regarding the TDS
data.results[].details_viewed_on	String	Date and time when the details were viewed
status_code	Integer	HTTP status code of the response
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": "tax_payer_view_vqBUDDdPChllpgjhbbwc",
        "tan_number": "DELS01235E",
        "pan_number": "DQABC1234F",
        "year": "2020",
        "type_of_return": "salary",
        "quarters": [
            "Q4"
        ],
        "results": [
            {
                "quarter": "Q4",
                "type_of_return": "Salary",
                "count_of_records": 1,
                "remarks": "Quarterly statement filed",
                "details_viewed_on": "2024-03-15T15:41:00"
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid TAN/PAN

Authentication Error

Record Not Found

{
    "status_code": 400,
    "success": false,
    "message": "Invalid TAN or PAN number format",
    "message_code": "invalid_input"
}

The provided TAN or PAN number does not match the required format.

Integration Best Practices

Security Recommendations

Store API credentials securely and never expose them in client-side code

Implement proper error handling to avoid exposing sensitive information

Rotate JWT tokens periodically and implement token expiration

Use HTTPS for all API communications to ensure data encryption

User Experience Guidelines

Implement proper validation for TAN and PAN numbers before making API calls

Display clear error messages to users when TDS information is not available

Cache responses when appropriate to improve application performance

Provide contextual help for users to understand the TDS information returned

Code Samples

cURL

Python

Node.js

Related APIs

PAN Verification API - Verify PAN card details of individuals and entities

TAN Verification API - Verify Tax Deduction Account Number details

ITR Status API - Check Income Tax Return filing status

GST Verification API - Verify GST registration details

Compliance and Legal Considerations

This API provides access to tax-related information which may be subject to privacy regulations. Ensure you have proper consent before accessing an individual's or organization's tax information. The data should be used in compliance with applicable tax laws and data protection regulations. Unauthorized access or misuse of tax information may result in legal penalties.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/tan/tds-check' \ --header 'Content-Type: application/json' \ --data-raw '{ "tan_number": "DELS01235E", "pan_number": "DQABC1234F", "year": "2020", "quarter": "Q4", "type_of_return": "salary" }'

{ "data": { "client_id": "tax_payer_view_vqBUDDdPChllpgjhbbwc", "tan_number": "DELS01235E", "pan_number": "DQABC1234F", "year": "2020", "type_of_return": "salary", "quarters": [ "Q4" ], "results": [ { "quarter": "Q4", "type_of_return": "Salary", "count_of_records": 1, "remarks": "Quarterly statement filed", "details_viewed_on": "2024-03-15T15:41:00" } ] }, "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 ********************

TDS Check

TDS Check#

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

TDS Check

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples