Search HSN Code

Endpoint Overview

POST /api/v1/corporate/search-hsn-code

Description

The HSN Code Search API enables developers to search and retrieve Harmonized System of Nomenclature (HSN) codes based on product or service descriptions. This intelligent search endpoint helps businesses accurately identify the correct HSN codes for their goods or services, which is essential for GST compliance, tax calculations, and regulatory reporting in India.

The API accepts a natural language description of a product or service and returns a ranked list of matching HSN codes with their official descriptions. This eliminates the manual effort of browsing through extensive HSN code lists and reduces the risk of classification errors.

Key Benefits

Instant HSN Code Discovery: Search thousands of HSN codes using simple product descriptions

Dual Category Support: Separate search capability for both goods and services

Accurate Tax Classification: Ensure correct GST rates by identifying the right HSN/SAC codes

Compliance Ready: Maintain regulatory compliance with proper HSN code classification for invoicing and returns

Use Cases

E-commerce & Retail

Manufacturing & Distribution

Accounting & ERP Systems

Product Catalog Management: Automatically assign HSN codes to new products added to inventory systems

Invoice Generation: Dynamically populate HSN codes on sales invoices based on product descriptions

Multi-vendor Marketplaces: Help sellers correctly classify their products for GST compliance

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.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for API authentication. Format: `Bearer <JWT_TOKEN>`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
hsn_descriptions	string	Yes	Natural language description of the product or service to search for (e.g., "car", "mobile phone", "consulting services")
category	string	Yes	Classification category for the search. Accepted values: `"goods"` for physical products or `"services"` for service-based offerings

Example Request

{
    "hsn_descriptions": "car",
    "category": "goods"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding the search results and metadata
data.client_id	string	Unique identifier for this search request, useful for tracking and debugging
data.input_hsn_descriptions	string	Echo of the search query that was submitted
data.hsn_list	array	Array of matching HSN codes with descriptions, ordered by relevance
data.hsn_list[].hsn_code	string	The HSN or SAC code (6 to 8 digits)
data.hsn_list[].description	string	Official description of the HSN/SAC code
status_code	integer	HTTP status code of the response (200 for success)
success	boolean	Indicates whether the API call was successful
message	string	Human-readable message describing the result
message_code	string	Machine-readable code for the message status

Example Successful Response

{
    "data": {
        "client_id": "search_hsn_code_nLTykRWwzqnInsBxvXhn",
        "input_hsn_descriptions": "car",
        "hsn_list": [
            {
                "hsn_code": "87036030",
                "description": "Motor cars"
            },
            {
                "hsn_code": "950823",
                "description": "DODGEEM CARS"
            },
            {
                "hsn_code": "95082300",
                "description": "DODGEEM CARS"
            },
            {
                "hsn_code": "87032491",
                "description": "MOTOR CARS"
            },
            {
                "hsn_code": "87119010",
                "description": "SIDE CARS"
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Invalid Category

Missing Required Field

No Results Found

{
    "success": false,
    "status_code": 401,
    "message": "Unauthorized access. Invalid or missing Bearer token",
    "message_code": "unauthorized"
}

This error occurs when the JWT Bearer token is missing, invalid, or expired. Verify that your token is correctly formatted and hasn't expired.

Integration Best Practices

Security Recommendations

Token Management: Store JWT tokens securely using environment variables or secure vaults, never hardcode them in your application

HTTPS Only: Always use HTTPS endpoints to ensure encrypted communication between your application and the API

Token Rotation: Implement automatic token refresh mechanisms before expiration to maintain uninterrupted service

Rate Limiting: Implement client-side rate limiting and request throttling to avoid overwhelming the API

Error Logging: Log all API interactions with sanitized data (exclude sensitive tokens) for audit and debugging purposes

User Experience Guidelines

Search Optimization: Use clear, specific product descriptions for better match accuracy (e.g., "cotton t-shirt" instead of just "shirt")

Result Presentation: Display multiple matching HSN codes to users when available, allowing them to select the most appropriate one

Caching Strategy: Cache frequently searched HSN codes locally to reduce API calls and improve response times

Fallback Mechanism: Provide users with manual HSN code entry options when automated search doesn't yield satisfactory results

Validation Feedback: Show clear validation messages when category selection doesn't match the product type

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

The HSN codes returned by this API are based on the official Harmonized System of Nomenclature maintained by the World Customs Organization and adopted by the Indian government for GST purposes. While the API provides accurate matching based on descriptions, businesses are ultimately responsible for selecting and using the correct HSN/SAC codes for their products and services. Incorrect classification may lead to GST rate discrepancies and potential compliance issues. It is recommended to consult with tax professionals for complex or ambiguous product classifications, especially for high-value transactions or items that may fall under multiple categories.

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/corporate/search-hsn-code' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "hsn_descriptions": "car", "category": "goods" }'

{ "data": { "client_id": "search_hsn_code_nLTykRWwzqnInsBxvXhn", "input_hsn_descriptions": "car", "hsn_list": [ { "hsn_code": "87036030", "description": "Motor cars" }, { "hsn_code": "950823", "description": "DODGEEM CARS" }, { "hsn_code": "95082300", "description": "DODGEEM CARS" }, { "hsn_code": "87032491", "description": "MOTOR CARS" }, { "hsn_code": "87119010", "description": "SIDE CARS" } ] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

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