TAN Advanced

Endpoint Overview

POST /api/v1/tan/tan-advanced

Description

The TAN Advanced API provides comprehensive information about a Tax Deduction and Collection Account Number (TAN) holder in India. This endpoint delivers detailed data including the holder's full name, address, contact information, and TAN allotment date. It's designed for organizations that need to verify TAN details for compliance, onboarding, or verification purposes.

Key Benefits

Comprehensive Verification: Access complete TAN holder details including address and contact information

Reliable Data Source: Direct verification against official TAN records

Streamlined Compliance: Simplify regulatory compliance with accurate TAN verification

Enhanced Due Diligence: Strengthen KYC processes with detailed entity information

Use Cases

Financial Services

Corporate Services

Tax Consultancy

Verify TAN details during corporate client onboarding

Validate tax deduction credentials for payment processing

Enhance KYC verification for corporate accounts

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
id_number	String	Yes	Valid TAN number to be verified

Example Request

{
    "id_number": "RTKT06731E"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the TAN verification results
data.client_id	String	Unique identifier for the verification request
data.tan	String	The verified TAN number
data.details	Object	Comprehensive information about the TAN holder
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Additional information about the response (null if successful)
message_code	String	Code indicating the status of the response

Details Object

Parameter	Type	Description
full_name	String	Complete name of the TAN holder
first_name	String	First name of the TAN holder
middle_name	String	Middle name of the TAN holder
last_name	String	Last name of the TAN holder
tan_allotment_date	String	Date when TAN was allotted (YYYY-DD-MM format)
address	Object	Complete address details of the TAN holder
email_1	String	Primary email address of the TAN holder
email_2	String	Alternative email address of the TAN holder
phone_number	String	Contact number of the TAN holder

Address Object

Parameter	Type	Description
line_1	String	House number or building name
line_2	String	Colony or area name
line_3	String	Landmark information
line_4	String	Area details
line_5	String	City name
state_code	Integer	Numeric code representing the state
zip	String	Postal code
full	String	Complete formatted address

Example Successful Response

{
    "data": {
        "client_id": "tan_advanced_eMtQfmiASeAsvXeqojXj",
        "tan": "ABKT12345E",
        "details": {
            "full_name": "SOLUTIONS PRIVATE LIMITED",
            "first_name": "",
            "middle_name": "",
            "last_name": "",
            "tan_allotment_date": "2050-12-18",
            "address": {
                "line_1": "H.NO 123 ,SHIV COLONY",
                "line_2": ",",
                "line_3": "",
                "line_4": "",
                "line_5": "PANCHKULA",
                "state_code": 99,
                "zip": "123456",
                "full": "H.NO.123 SHIV COLONY , PANCHKULA 123456"
            },
            "email_1": "ABCD@LIVE.IN",
            "email_2": "",
            "phone_number": "1234567890"
        }
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Invalid TAN

TAN Not Found

Authentication Error

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

The provided TAN number format is incorrect or invalid.

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

Use HTTPS for all API communications to ensure data encryption

Rotate JWT tokens periodically and implement token expiration

User Experience Guidelines

Implement proper validation for TAN format before making API calls

Display a user-friendly message when TAN verification fails

Cache successful verification results to improve performance

Provide clear feedback during the verification process

Code Samples

cURL

Python

Node.js

Related APIs

TAN Basic Verification: Simple verification of TAN number validity

PAN Verification: Verify Permanent Account Number details

GST Verification: Validate Goods and Services Tax registration information

Business Verification: Comprehensive business entity verification

Compliance and Legal Considerations

The TAN Advanced API provides access to sensitive tax-related information. Ensure you have proper authorization to access this data and comply with all applicable data protection regulations. Usage of this API should align with the Information Technology Act, 2000 and relevant Income Tax Department guidelines in India. Ensure you have appropriate consent before verifying third-party TAN information.

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/tan/tan-advanced' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "RTKT06731E" }'

{ "data": { "client_id": "tan_advanced_eMtQfmiASeAsvXeqojXj", "tan": "ABKT12345E", "details": { "full_name": "SOLUTIONS PRIVATE LIMITED", "first_name": "", "middle_name": "", "last_name": "", "tan_allotment_date": "2050-12-18", "address": { "line_1": "H.NO 123 ,SHIV COLONY", "line_2": ",", "line_3": "", "line_4": "", "line_5": "PANCHKULA", "state_code": 99, "zip": "123456", "full": "H.NO.123 SHIV COLONY , PANCHKULA 123456" }, "email_1": "ABCD@LIVE.IN", "email_2": "", "phone_number": "1234567890" } }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

TAN Advanced

TAN Advanced#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Details Object#

Address Object#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

TAN Advanced

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Details Object

Address Object

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples