HS Code Lookup

POST/v1/compliance/hs-lookup$0.05 per call

Look up HS/HTS tariff codes by commodity description or HS code prefix using USITC database with AI-powered classification.

Send an Idempotency-Key header to retry safely.

Request body

Field	Type	Description
commodityDescriptionoptional	string	At least one of commodityDescription or hsCode is required max length 2000
hsCodeoptional	string	max length 20
countryoptional	string	max length 3
useAIoptional	boolean	Enable AI-powered classification default false
maxResultsoptional	integer	min 1 · max 50 · default 10
aiModeoptional	string	Send "off" to forbid all LLM processing for this request. An account-level setting can also turn AI off; a request can never turn it back on. one of "on", "off" · default "on"

Response fields

Field	Type	Description
success	boolean	e.g. `true`
data	object
data.id	string	e.g. `hsl_9a774f23bf255378`
data.query	string	e.g. `laptop computer`
data.method	string	e.g. `KEYWORD_SEARCH`
data.totalMatches	number	e.g. `6`
data.matches	array
data.matches[].htsCode	string	e.g. `9017.20.80.40`
data.matches[].description	string	e.g. `Hand operated input devices which transmit position data to c…`
data.matches[].chapter	number	e.g. `90`
data.matches[].chapterDescription	string	e.g.
data.matches[].section	number	e.g. `0`
data.matches[].sectionDescription	string	e.g.
data.matches[].generalDutyRate	string	e.g. `4.6%`
data.matches[].unit	string	e.g. `No.`
data.matches[].confidence	number	e.g. `1`
data.matches[].matchType	string	e.g. `KEYWORD`
data.aiClassification	null
data.dataSource	object
data.dataSource.name	string	e.g. `USITC Harmonized Tariff Schedule (PostgreSQL)`
data.dataSource.edition	string	e.g. `current USITC revision as last synced`
data.dataSource.totalEntries	number	e.g. `29861`
data.dataSource.lastUpdated	string	e.g. `2026-10-20`
data.processedAt	string	e.g. `2026-11-04T09:01:10.012Z`
meta	object
meta.requestId	string	e.g. `hsl_9a774f23bf255378`
meta.timestamp	string	e.g. `2026-11-04T09:01:10.012Z`
meta.processingTimeMs	number	e.g. `285`
meta.dataSource	object
meta.dataSource.name	string	e.g. `USITC Harmonized Tariff Schedule (PostgreSQL)`
meta.dataSource.provenance	string	e.g. `database`

Fields are read from a real response captured 2026-11-04, shortened. Optional fields may be absent in other responses.

Errors

400 invalid request
401 missing or bad key
403 not in your plan
429 rate limited, see Retry-After
402 payment required
5xx retry with backoff

Error bodies and codes are described in Error codes and troubleshooting.

curl -X POST "https://api.compliancegrid.ai/v1/compliance/hs-lookup" \
  -H "Authorization: Bearer $CG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "commodityDescription": "laptop computer",
    "aiMode": "off"
  }'

Try it in the sandbox

Runs against sandbox.api.compliancegrid.ai with your own sandbox key, which stays in this browser. Sandbox responses are mock data. Get a free key.

Sandbox key

Remember for this tab

Request body (JSON)

Example response · captured from production 2026-11-04 · shortened

{
  "success": true,
  "data": {
    "id": "hsl_9a774f23bf255378",
    "query": "laptop computer",
    "method": "KEYWORD_SEARCH",
    "totalMatches": 6,
    "matches": [
      {
        "htsCode": "9017.20.80.40",
        "description": "Hand operated input devices which transmit position data to computer processors or displays (digitizers)",
        "chapter": 90,
        "chapterDescription": "",
        "section": 0,
        "sectionDescription": "",
        "generalDutyRate": "4.6%",
        "unit": "No.",
        "confidence": 1,
        "matchType": "KEYWORD"
      },
      {
        "htsCode": "8471.30.01.00",
        "description": "Portable automatic data processing machines, weighing not more than 10 kg, consisting of at least a central processing unit, a keyboard and a display",
        "chapter": 84,
        "chapterDescription": "",
        "section": 0,
        "sectionDescription": "",
        "generalDutyRate": "Free",
        "unit": "No.",
        "confidence": 0.95,
        "matchType": "KEYWORD"
      }
    ],
    "aiClassification": null,
    "dataSource": {
      "name": "USITC Harmonized Tariff Schedule (PostgreSQL)",
      "edition": "current USITC revision as last synced",
      "totalEntries": 29861,
      "lastUpdated": "2026-10-20"
    },
    "processedAt": "2026-11-04T09:01:10.012Z"
  },
  "meta": {
    "requestId": "hsl_9a774f23bf255378",
    "timestamp": "2026-11-04T09:01:10.012Z",
    "processingTimeMs": 285,
    "dataSource": {
      "name": "USITC Harmonized Tariff Schedule (PostgreSQL)",
      "provenance": "database"
    }
  }
}