TAN Company Search

Endpoint Overview

POST /api/v1/tan/company-search

Description

The TAN Company Search API enables you to search for companies based on their name and state, returning their Tax Deduction and Collection Account Number (TAN) details. This API helps verify the existence of companies and retrieve their official TAN information from government records, which is essential for tax compliance and business verification processes.

Key Benefits

Quickly verify company existence and retrieve official TAN details

Filter search results by state to narrow down matches

Option for exact name matching to ensure precision in company identification

Streamlined verification process for tax and compliance workflows

Use Cases

Financial Services

Tax Compliance

Business Services

Verify business client identities during onboarding processes

Validate company tax information before establishing financial relationships

Automate compliance checks for KYC (Know Your Customer) requirements

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
company	String	Yes	The name of the company to search for
state	String	Yes	The state where the company is registered
exact_match	Boolean	No	When set to true, returns only exact matches of the company name (default: false)
search_size	String	No	Search size
fuzziness	Boolean	No	Fuzziness
auto_complete	Boolean	No	Auto Complete

Example Request

{
    "company": "ABC PRIVATE LIMITED",
    "state": "Delhi",
    "exact_match": true
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the search results and metadata
data.client_id	String	Unique identifier for the API request
data.search_company_name	String	The company name that was searched
data.search_size	Number	Maximum number of search results to return
data.search_state	String	The state that was searched
data.exact_match	Boolean	Whether exact matching was used
data.hits	Number	Number of companies found matching the criteria
data.search_data	Array	List of companies matching the search criteria
data.search_data[].tan	String	Tax Deduction and Collection Account Number
data.search_data[].company_name	String	Name of the company
status_code	Number	HTTP status code of the response
success	Boolean	Indicates if the API call was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "client_id": "tan_company_search_MrZzXqGKYgZoewbEymGS",
        "search_company_name": "ABC PRIVATE LIMITED",
        "search_size": 10,
        "search_state": "DELHI",
        "exact_match": true,
        "hits": 1,
        "search_data": [
            {
                "tan": "DELS71234E",
                "company_name": "ABC PRIVATE LIMITED"
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Input

Authentication Error

No Results

{
    "status_code": 400,
    "success": false,
    "message": "Invalid input parameters",
    "message_code": "invalid_input"
}

This error occurs when required parameters are missing or in incorrect 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 don't reuse them across different applications

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

User Experience Guidelines

Implement progressive search to help users find companies without knowing the exact name

Provide clear feedback when no results are found and suggest alternative search terms

Consider caching frequent searches to improve response times

Implement proper validation for company names and state inputs before making API calls

Code Samples

cURL

Python

Node.js

Related APIs

PAN Verification API: Verify Permanent Account Number details for individuals and entities

GST Verification API: Verify Goods and Services Tax registration details for businesses

Company Information API: Retrieve comprehensive company information including directors and financial data

Compliance and Legal Considerations

The TAN information retrieved through this API is subject to Indian tax regulations. The data should be used in compliance with the Income Tax Act and related regulations. This API should not be used for mass harvesting of TAN information, and usage should be limited to legitimate business verification purposes. Ensure you have appropriate consent when verifying third-party business 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/company-search' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "company": "ABC PRIVATE LIMITED", "state": "Delhi", "exact_match": true }'

{ "data": { "client_id": "tan_company_search_MrZzXqGKYgZoewbEymGS", "search_company_name": "ABC PRIVATE LIMITED", "search_size": 10, "search_state": "DELHI", "exact_match": true, "hits": 1, "search_data": [ { "tan": "DELS71234E", "company_name": "ABC PRIVATE LIMITED" } ] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

TAN Company Search

TAN Company Search#

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

TAN Company Search

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples