TIN Verification

Endpoint Overview

POST /api/v1/tin/tin-verification

Description

The TIN Verification API allows you to validate and retrieve information associated with a Taxpayer Identification Number (TIN) in India. This endpoint verifies the authenticity of a TIN and returns comprehensive details about the registered taxpayer, including registration status, dealer information, and validity dates.

Key Benefits

Instant verification of TIN numbers against official government records

Comprehensive taxpayer details including registration status and validity

Reduces fraud risk by confirming the legitimacy of business entities

Streamlines compliance processes for financial and business transactions

Use Cases

Financial Services

E-commerce

Enterprise Solutions

Verify business identity during customer onboarding

Validate vendor tax credentials before processing payments

Ensure tax compliance during loan application 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 format
Content-Type	Yes	Application/json

Request Body

Parameter	Type	Required	Description
tin_number	String	Yes	Taxpayer Identification Number (TIN) to be verified

Example Request

{
    "tin_number": "12345678915"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the verification result data
data.client_id	String	Unique identifier for the verification request
data.tin_number	String	The TIN number that was verified
data.cst_number	String	Central Sales Tax (CST) Number associated with the TIN
data.dealer_name	String	Registered name of the taxpayer/business
data.dealer_address	String	Registered address of the taxpayer/business
data.state_name	String	State where the taxpayer is registered
data.pan_number	String	Permanent Account Number (PAN) of the taxpayer
data.registration_date	String	Date of TIN registration (YYYY-MM-DD format)
data.valid_upto	String	Expiry date of the registration (YYYY-MM-DD format)
data.registration_status	String	Current status of the registration (e.g., Active, Cancelled)
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the verification was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "client_id": "tin_verification_bZNrBkyzCMfOfkqteenz",
        "tin_number": "12345678915",
        "cst_number": "12345678915",
        "dealer_name": "RAM PERFURMERWORKS",
        "dealer_address": "PLOT NO-XX-21",
        "state_name": "Odisha",
        "pan_number": "NOT AVAILABLE",
        "registration_date": "1992-12-16",
        "valid_upto": "2013-07-20",
        "registration_status": "Cancelled"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid TIN

Authentication Error

{
    "status_code": 422,
    "success": false,
    "message": "Verification Failed.",
    "message_code": "verification_failed"
}

The provided TIN number is not in the correct format or contains invalid characters.

Integration Best Practices

Security Recommendations

Store API keys 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 clear error messages for end-users when verification fails

Add validation for TIN format before submitting to the API

Display verification results in a user-friendly format with clear status indicators

Implement caching strategies to improve response times for frequently verified TINs

Code Samples

cURL

Python

Node.js

Related APIs

PAN Verification API: Verify Permanent Account Number details

GST Verification API: Validate Goods and Services Tax registration

Business Verification API: Comprehensive business entity verification

Document OCR API: Extract information from tax documents automatically

Compliance and Legal Considerations

This API accesses government tax records and should be used in compliance with data privacy regulations. The information retrieved should only be used for legitimate business purposes such as KYC (Know Your Customer), vendor verification, or regulatory compliance. Ensure you have appropriate consent from the entity whose TIN is being verified when required by applicable laws.

{ "data": { "client_id": "tin_verification_bZNrBkyzCMfOfkqteenz", "tin_number": "12345678915", "cst_number": "12345678915", "dealer_name": "RAM PERFURMERWORKS", "dealer_address": "PLOT NO-XX-21", "state_name": "Odisha", "pan_number": "NOT AVAILABLE", "registration_date": "1992-12-16", "valid_upto": "2013-07-20", "registration_status": "Cancelled" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

TIN Verification

TIN Verification#

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

TIN Verification

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples