TIN Format Verification API

Endpoint Overview

POST /api/v1/tin/tin-format-verification

Description

The TIN Format Verification API is a powerful validation service that verifies the format structure of Tax Identification Numbers (TINs) for different countries. This endpoint analyzes the provided TIN against country-specific formatting rules and patterns to determine if the number follows the correct format structure required by that jurisdiction's tax authority.

The API provides instant validation results, identifying the specific format type (such as Permanent Account Number for India) and confirming whether the TIN adheres to the expected format pattern. This service is essential for businesses operating across multiple jurisdictions who need to validate tax identification numbers during customer onboarding, compliance verification, or financial transaction processing.

Key Benefits

Instant Format Validation: Real-time verification of TIN format compliance across multiple countries

Country-Specific Rules: Validates against jurisdiction-specific TIN formatting requirements

Format Identification: Returns the specific format name and type for validated TINs

Compliance Support: Helps ensure adherence to international tax identification standards

Use Cases

Financial Services

E-commerce

Enterprise

Customer onboarding verification for international banking services

Tax compliance validation for cross-border financial transactions

Know Your Customer (KYC) processes for global financial institutions

Anti-money laundering (AML) compliance checks

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 API authentication (JWT format)
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
tin_number	String	Yes	The Tax Identification Number to be validated
country	String	Yes	The country code or name for which the TIN format should be validated

Example Request

{
  "tin_number": "CZCPG1234L",
  "country": "India"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container object for the verification results
data.client_id	String	Unique identifier for the verification request
data.tin_number	String	The TIN number that was verified
data.country	String	The country for which verification was performed
data.id_type	String	The type of identification (typically "any" for TIN verification)
data.format_name	String	The specific name of the TIN format (e.g., "Permanent Account Number")
data.is_valid_format	Boolean	Indicates whether the TIN follows the correct format structure
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates whether the API call was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
  "data": {
    "client_id": "tin_format_verification_rQnswdmnhyjRXlwsjimX",
    "tin_number": "CZCPG1234L",
    "country": "India",
    "id_type": "any",
    "format_name": "Permanent Account Number",
    "is_valid_format": true
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Invalid Authentication

Invalid Request Format

Unsupported Country

{
    "error": null,
    "message": "Your token is invalid. Please ensure that correct token is being used.",
    "status_code": 401,
    "success": false,
    "message_code": "invalid_token"
}

Returned when the JWT Bearer token is missing, invalid, or expired.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and implement token refresh mechanisms

Use HTTPS for all API communications to protect sensitive TIN data

Implement proper error handling to avoid exposing sensitive information

Log API requests for audit purposes while ensuring compliance with data protection regulations

User Experience Guidelines

Provide clear feedback to users about TIN format requirements before submission

Implement client-side validation to reduce unnecessary API calls

Display meaningful error messages that help users correct invalid TIN formats

Consider implementing progressive validation for better user experience

Code Samples

cURL

Python

Node.js

Related APIs

TIN Verification API: Complete TIN validation including authenticity verification with tax authorities

GST Verification API: Goods and Services Tax number validation and business information retrieval

PAN Verification API: Permanent Account Number validation and holder information verification

Corporate Identity Verification: Company registration and directorship verification services

Compliance and Legal Considerations

Ensure compliance with local data protection and privacy regulations when processing TIN data

Implement appropriate data retention policies for verification logs and results

Be aware that TIN format validation does not guarantee the authenticity or active status of the tax identification number

Consider jurisdictional requirements for cross-border tax identification number processing and storage

Maintain audit trails for compliance reporting and regulatory requirements

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/tin/tin-format-verification' \ --header 'Content-Type: application/json' \ --data-raw '{ "tin_number": "CZCPG1234L", "country": "India" }'

{ "data": { "client_id": "tin_format_verification_rQnswdmnhyjRXlwsjimX", "tin_number": "CZCPG1234L", "country": "India", "id_type": "any", "format_name": "Permanent Account Number", "is_valid_format": true }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

TIN Format Verification

TIN Format Verification API#

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