Get HTS Codes - htsapi.com

Search HTS Codes

curl --request GET \
  --url https://htsapi.com/v1/hts \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "id": 123,
      "description": "<string>",
      "code": "<string>",
      "normalized_code": "<string>",
      "indent": 123,
      "chapter": "<string>",
      "heading": "<string>",
      "subheading": "<string>",
      "rates": {
        "general": "<string>",
        "special": "<string>",
        "other": "<string>"
      },
      "units": [
        "<string>"
      ],
      "footnotes": [
        {
          "marker": "<string>",
          "value": "<string>"
        }
      ]
    }
  ],
  "meta": {
    "total": 123,
    "page": 123,
    "limit": 123,
    "total_pages": 123
  },
  "clarification": {
    "needed": true,
    "message": "<string>",
    "suggestions": [
      "<string>"
    ],
    "grouped_by": "heading"
  },
  "ai_context": "<string>"
}

GET

hts

Search HTS Codes

curl --request GET \
  --url https://htsapi.com/v1/hts \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "id": 123,
      "description": "<string>",
      "code": "<string>",
      "normalized_code": "<string>",
      "indent": 123,
      "chapter": "<string>",
      "heading": "<string>",
      "subheading": "<string>",
      "rates": {
        "general": "<string>",
        "special": "<string>",
        "other": "<string>"
      },
      "units": [
        "<string>"
      ],
      "footnotes": [
        {
          "marker": "<string>",
          "value": "<string>"
        }
      ]
    }
  ],
  "meta": {
    "total": 123,
    "page": 123,
    "limit": 123,
    "total_pages": 123
  },
  "clarification": {
    "needed": true,
    "message": "<string>",
    "suggestions": [
      "<string>"
    ],
    "grouped_by": "heading"
  },
  "ai_context": "<string>"
}

Search HTS codes using full-text search, code prefix matching, or hierarchical filtering. Returns paginated results with optional clarification suggestions.

Parameters

Parameter	Type	Required	Description
`q`	string	No	Full-text search query (max 500 chars)
`code`	string	No	Exact or prefix code match (e.g., ‘8517’ or ‘8517.12’)
`chapter`	string	No	Filter by chapter (2 digits, e.g., ‘85’)
`heading`	string	No	Filter by heading (4 digits, e.g., ‘8517’)
`subheading`	string	No	Filter by subheading (6 digits, e.g., ‘851712’)
`page`	integer	No	Page number (default: 1, min: 1)
`limit`	integer	No	Results per page (default: 25, min: 1, max: 100)

Example Request

curl -X GET "https://htsapi.com/v1/hts?q=coffee&page=1&limit=25" \
  -H "Authorization: Bearer your_hts_api_key"

Example Response

{
  "data": [
    {
      "id": 12345,
      "code": "0901.11.00",
      "normalized_code": "09011100",
      "description": "Coffee, not roasted, not decaffeinated",
      "indent": 2,
      "chapter": "09",
      "heading": "0901",
      "subheading": "090111",
      "rates": {
        "general": "Free",
        "special": "Free (A+,AU,BH,CA...)",
        "other": "Free"
      },
      "units": [],
      "footnotes": []
    }
  ],
  "meta": {
    "total": 45,
    "page": 1,
    "limit": 25,
    "total_pages": 2
  },
  "clarification": {
    "needed": true,
    "message": "Your search for \"coffee\" returned multiple classifications. Please refine your search:",
    "suggestions": [
      "Unroasted (green) coffee - 0901.11 or 0901.12",
      "Roasted coffee - 0901.21 or 0901.22",
      "Decaffeinated coffee - specify roasted (0901.22) or unroasted (0901.12)",
      "Note: Instant/soluble coffee is classified under 2101.11, not 0901"
    ],
    "grouped_by": "heading"
  }
}

Clarifications

When a search returns multiple classifications, the API includes a clarification object with suggestions to help refine your search. Business plans can also receive ai_context with AI-assisted guidance.

Authorizations

Authorization

string

header

required

API key as Bearer token. Format: Bearer your_hts_api_key

Query Parameters

string

Full-text search query

Maximum string length: 500

code

string

Exact or prefix code match (e.g., '8517' or '8517.12')

Maximum string length: 50

chapter

string

Filter by chapter (2 digits, e.g., '85')

Maximum string length: 10

heading

string

Filter by heading (4 digits, e.g., '8517')

Maximum string length: 10

subheading

string

Filter by subheading (6 digits, e.g., '851712')

Maximum string length: 10

page

integer

default:1

Page number (default: 1)

Required range: x >= 1

limit

integer

default:25

Results per page (max: 100, default: 25)

Required range: 1 <= x <= 100

Response

HTS Code response with pagination

data

object[]

Show child attributes

API Reference

​Parameters

​Example Request

​Example Response

​Clarifications

Authorizations

Query Parameters

Response

Parameters

Example Request

Example Response

Clarifications