HS Code

GET/v0/hs-code

Validates and looks up a Harmonized System (HS) tariff code used in international trade classification. Accepts 2-digit (chapter), 4-digit (heading), or 6-digit (subheading) codes. Returns the description and full hierarchy (chapter → heading → subheading). Dots, dashes, and spaces in the input are stripped automatically.

Guides: Node.js · Python

Try it

Query Parameters

Param	Type	Required	Description
value	string	Yes	The HS code to validate. Accepts 2, 4, or 6 digits (e.g. `84`, `8471`, `847130`).

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/hs-code?value=8471.30"

Response Fields

Field	Type	Description
valid	boolean	Whether the code is a recognised HS code
code	string	The normalised HS code (digits only)
level	string	`chapter`, `heading`, or `subheading`
description	string	Official WCO description of this code
formatted	string	Human-readable formatted code (e.g. `84.71.30`)
chapter	object	Parent chapter (for headings and subheadings)
heading	object	Parent heading (for subheadings only)
error	string	Error message when invalid

Example Response — Heading

{
  "valid": true,
  "code": "8471",
  "level": "heading",
  "description": "Automatic data-processing machines and units thereof",
  "formatted": "84.71",
  "chapter": {
    "code": "84",
    "description": "Nuclear reactors, boilers, machinery and mechanical appliances; parts thereof"
  }
}

Example Response — Chapter

{
  "valid": true,
  "code": "84",
  "level": "chapter",
  "description": "Nuclear reactors, boilers, machinery and mechanical appliances; parts thereof",
  "formatted": "84"
}

GET/v0/hs-code/list

Returns HS codes, optionally filtered by chapter and/or level. Useful for building hierarchical code selectors.

Query Parameters

Param	Type	Required	Description
chapter	string	No	Filter by chapter (2-digit code, e.g. `84`)
level	string	No	Filter by level: `chapter`, `heading`, or `subheading`

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/hs-code/list?chapter=84&level=heading"

Example Response

[
  { "code": "8401", "level": "heading", "description": "Nuclear reactors; fuel elements (cartridges), non-irradiated, for nuclear reactors; machinery and apparatus for isotopic separation" },
  { "code": "8402", "level": "heading", "description": "Steam or other vapour generating boilers" },
  { "code": "8403", "level": "heading", "description": "Central heating boilers other than those of heading 84.02" },
  ...
]