ClassifyHQ API Documentation

REST APIs for Harmonized System tariff data and pre-shipment classification validation. JSON responses, ISO 8601 timestamps, 100 req/min rate limit.

Tariff Reference API

Free, public, unauthenticated. Browse sections, chapters, headings, subheadings, and country-specific tariff lines for US, EU, UK, Canada, and Norway.

No API key required.

Pre-shipment Validation API

Authenticated. Validate a proposed HS code before booking a shipment. Returns a verdict with per-rule findings, matched code, and required documents.

Read full reference →

Base URL

https://classifyhq.ai/api
GET /api/sections

List all 21 HS sections with their chapter ranges.

Example Request

curl https://classifyhq.ai/api/sections

Example Response

{
  "I": {
    "roman": "I",
    "name": "Live Animals; Animal Products",
    "chapter_range": [1, 5],
    "chapters": [
      {"code": "01", "description": "Live animals", "level": "chapter"}
    ]
  }
}
GET /api/sections/{section}/chapters

List all chapters within a section.

Parameters

section string Roman numeral (e.g. XI, IV)

Example Request

curl https://classifyhq.ai/api/sections/XI/chapters

Example Response

[
  {"code": "50", "description": "Silk", "level": "chapter"},
  {"code": "51", "description": "Wool, fine or coarse animal hair...", "level": "chapter"}
]
GET /api/chapters/{code}/headings

List all 4-digit headings within a chapter.

Parameters

code string 2-digit chapter code (e.g. 51)

Example Request

curl https://classifyhq.ai/api/chapters/51/headings

Example Response

[
  {"code": "5101", "description": "Wool, not carded or combed", "level": "heading"},
  {"code": "5102", "description": "Fine or coarse animal hair", "level": "heading"}
]
GET /api/headings/{code}/subheadings

List all 6-digit subheadings under a heading.

Parameters

code string 4-digit heading code (e.g. 5101)

Example Request

curl https://classifyhq.ai/api/headings/5101/subheadings

Example Response

[
  {"code": "510111", "description": "Greasy shorn wool", "level": "subheading"},
  {"code": "510119", "description": "Other greasy wool", "level": "subheading"}
]
GET /api/subheadings/{code}

Get details for a 6-digit HS subheading, including all country-specific tariff codes.

Parameters

code string 6-digit HS code (e.g. 510111)

Example Request

curl https://classifyhq.ai/api/subheadings/510111

Example Response

{
  "code": "510111",
  "description": "Greasy shorn wool",
  "level": "subheading",
  "countries": {
    "US": [{"code": "5101110020", "description": "...", "rate": "Free"}],
    "EU": [{"code": "5101110000", "description": "...", "rate": "0%"}],
    "CA": [],
    "NO": [],
    "GB": [{"code": "5101110000", "description": "...", "rate": "0%"}]
  }
}
GET /api/countries/{country}/{code}

Get a specific country tariff code entry.

Parameters

country string Country code: us, eu, ca, no, or gb
code string Country-specific tariff code

Example Request

curl https://classifyhq.ai/api/countries/us/5101110020

Example Response

{
  "code": "5101110020",
  "description": "Greasy shorn wool, Merino",
  "parent": "510111",
  "rate": "Free",
  "unit": "kg"
}
GET /api/search

Search across all HS codes by code number or keyword description.

Parameters

q string Search query (min 2 characters)
limit integer Max results (default 50)

Example Request

curl "https://classifyhq.ai/api/search?q=wool&limit=5"

Example Response

[
  {"code": "5101", "description": "Wool, not carded or combed", "level": "heading"},
  {"code": "510111", "description": "Greasy shorn wool", "level": "subheading"}
]
POST /api/validate

Validate a proposed HS classification before booking a shipment. Requires an API key (X-Api-Key header). Returns a verdict (pass/warn/fail) with per-rule findings, matched code, and required documents.

Parameters

hs_code string Proposed HS code (6, 8, or 10 digits)
description string Product description (optional but recommended)
origin_country string ISO 3166-1 alpha-2 code, e.g. CN, DK, US
destination_country string ISO 3166-1 alpha-2 code, e.g. US, GB, NO
declared_value number Declared value (positive)
currency string ISO 4217, e.g. USD
carrier string e.g. dhl-express, postnord (optional)

Example Request

curl -X POST https://classifyhq.ai/api/validate \ -H 'X-Api-Key: ck_live_…' \ -H 'Content-Type: application/json' \ -d '{"hs_code":"6109100012","description":"Cotton t-shirt, knitted","origin_country":"CN","destination_country":"US","declared_value":12.50,"currency":"USD"}'

Example Response

{
  "data": {
    "verdict": "warn",
    "matched_code": {"code": "6109100012", "description": "T-shirts, knitted, cotton"},
    "findings": [
      {"rule": "code_well_formed", "result": "pass", "message": "Code is 10 digits."},
      {"rule": "hs6_active", "result": "pass", "message": "Matched HS6: T-shirts, singlets and other vests; of cotton, knitted or crocheted"},
      {"rule": "country_code_active", "result": "pass", "message": "US tariff line: T-shirts, knitted, cotton"},
      {"rule": "country_pair_trap", "result": "warn", "message": "China-origin goods in chapter 61 may be subject to Section 301..."}
    ],
    "required_documents": [
      {"name": "Textile country of origin declaration", "reason": "CBP requires textile origin documentation per 19 CFR 102.21."}
    ]
  }
}