Skip to main content

Search HS codes by term

GET 
/company/categories/find

Search for matches in Harmonized System heading codes and descriptions (6 digits) and subheading codes (8-10 digits). Allows free-text search without needing to know the complete hierarchy.

Objective​

Facilitate the quick search of HS codes when the product name or a partial code is known, without navigating the complete hierarchical structure.

Use Cases​

  • Product Search: Find the HS code for tuna, machinery, textiles
  • Code Validation: Verify if a code exists and get its description
  • Autocomplete: Suggest codes as the user types a product name
  • Quick Classification: Find categories without exploring the entire hierarchy
  • Inventory Integration: Classify existing products in a catalog

Search Features​

  • Case-insensitive: Does not distinguish between uppercase/lowercase
  • Partial Match: Searches in titles (codes) and descriptions (labels)
  • 40 Result Limit: 20 headings + 20 subheadings
  • Alphabetical Ordering: Results sorted by code
  • Multiple Sources: Searches in heading and subheading collections

Search Flow​

flowchart TD
  A[Receive term] --> B{valid term?}
  B -->|No| C[404 USER_NOT_FOUND]
  B -->|Yes| D[Search headings - max 20]
  D --> E[Search subheadings - max 20]
  E --> F[Combine results]
  F --> G[Sort alphabetically]
  G --> H[Return array]

Important Notes​

  • Requires authentication with a company JWT token
  • The term can come from a query param, path param, or body (extracted from all)
  • The term is cleaned of single quotes before searching
  • Minimum 1 character required (spaces are trimmed)
  • Returns no results if there are no matches (empty array, not 404)

Request​

Responses​

HS codes matching the search

Response Headers