Integrate Codici HS code lookups into your systems using our REST API.
Include your API key in every request via the api-key header:
Or as a query parameter: ?api_key=YOUR_API_KEY
Manage API keys in your account.
Look up an HS code for a single product description.
| Parameter | Required | Description |
|---|---|---|
| description | required | Product description in any language |
| region | optional | Customs region (default: global). Options: global, usa, european_union, great_britain, canada, china, japan, australia, saudi_arabia, faroe_islands |
| language | optional | Response language (default: en). Options: en, nl, fr, et, fo |
Classify up to 100 product descriptions in a single call. The response is an array of result objects in the same order as the descriptions you sent.
Billing counts lookups, not API calls. Each description in the batch is one lookup against your monthly allowance, so a call containing 100 descriptions uses 100 lookups — batching saves round trips and time, not cost.
Where you stand this month: your plan, how many lookups it includes, how many you have used, how many remain, and any extras accrued beyond the allowance.
Your recent API usage records. This is metadata only — when each lookup happened, from which key and which IP. We never store the descriptions you send or the results we return, so there is no query content to retrieve here.
Every lookup comes back in a signed envelope. The data object holds the request
echo, an anonymous requestor reference, the classification result and our platform details.
hmac is an HMAC-SHA256 signature over data, so a saved result can be
proven to have come from us, unaltered — paste it into the
verification page to check.
result_not_used sits deliberately outside data and is
therefore not covered by the signature. It carries fields we have not yet curated into
result and will shrink over time, so treat it as transitional.
Field shapes do not change with the region you request.
confidence and each alternative's likelihood are fractions between
0 and 1 (so 0.9 means 90% confident).
hs_code is the six-digit WCO Harmonized System code, written xxxx.xx
everywhere. hts_code is the full national code, written the way that authority
writes it:
| Region | Code | Notation | Example |
|---|---|---|---|
| European Union | Combined Nomenclature (8) / TARIC (10) | digits only | 88040000 |
| Great Britain | UK commodity code (up to 10) | digits only | 8804000000 |
| United States | HTSUS (10) | xxxx.xx.xx.xx | 8211.92.90.30 |
| Other regions | national schedule | dotted pairs | 3901.20.00.99.999 |
Compare codes on their digits, not their punctuation — strip everything that isn't a digit and the values are directly comparable across regions.
You do not need to keep our exact JSON. To reproduce the signature: take the data
object, sort every key alphabetically at every level, trim leading and trailing whitespace from
every string value, serialise it compactly, and compute
HMAC-SHA256 over that with your shared secret. Key order, indentation and stray
whitespace therefore make no difference — only the field values do. result_not_used
sits outside data and is deliberately not signed.
cost is what this one lookup added on top of your fixed monthly fee: 0
while you are inside your allowance, your plan's per-extra-lookup price once past it.
/v1/lookup-batch returns an array of these objects, one per description.
| HTTP status | Code | Meaning |
|---|---|---|
| 400 | missing_param / invalid_param / invalid_json / too_many | Missing or invalid parameters (too_many = more than 100 descriptions in one batch) |
| 401 | missing_key / invalid_key / key_revoked | Missing, unknown or revoked API key |
| 402 | no_plan | No plan is active on the account, so lookups are unavailable — contact us to get set up |
| 429 | rate_limit | Rate limit exceeded |
| 500 | upstream_error | Internal error (upstream provider or system) |
Going over your included lookups is never an error — extra lookups are simply charged at your plan's per-lookup rate and appear on that month's invoice.