Endpoint

Classify HS code

Accepts a single description or a batch of up to 50 lines. Returns the recommended 6-digit HS code, a 10-digit HTS suggestion when available, plus a confidence score and reason string. Supply hs_code_printed to flag disagreements with what your supplier printed on the commercial invoice.

POST/v1/classify

Request body (single)

description

string (3 to 2000 chars)Required

Product description. More detail (material, function, packaging) yields higher confidence.

destination_country

string (ISO-2)Required

Destination country. Drives the tariff-schedule lookup.

hs_code_printed

string

HS code your supplier printed on the invoice. Set to have the classifier compare and flag disagreements.

confidence_threshold

number (0 to 1)

Minimum confidence before needs_review is false. Defaults to 0.85.

Request body (batch)

lines

ClassifyLine[]Required

1 to 50 line objects: { description, hs_code_printed? }.

destination_country

string (ISO-2)Required

Destination country shared by all lines.

confidence_threshold

number

Applied per-line.

Response 200 (single)

hs_6_code

string

6-digit HS heading.

Example: 851762

recommended_10_digit

string

10-digit HTS code when the destination has a national schedule (US, CA).

Example: 8517.62.00.90

confidence

number

0 to 1. Compare against confidence_threshold to decide needs_review.

reason

string

Prose explanation of why this code was chosen.

needs_review

boolean

True when confidence is below threshold or hs_code_printed disagrees.

candidates

array

Top-N alternative codes with scores.

disagreement_with_printed

boolean

True when hs_code_printed differs from the recommendation.

Response 200 (batch)

results

ClassificationResult[]

Per-line result in the input order.

needs_review

int[]

Indices of results that need human review.

consistency

object

common_chapter + outlier_indices for shipments where most lines share a chapter and a few outliers do not.

Example request

curl https://www.landedfees.com/api/v1/classify \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Wireless bluetooth earbuds with charging case",
  "destination_country": "US"
}'

Endpoint

Classify HS code

POST/v1/classify

Request body (single)

description

string (3 to 2000 chars)Required

Product description. More detail (material, function, packaging) yields higher confidence.

destination_country

string (ISO-2)Required

Destination country. Drives the tariff-schedule lookup.

hs_code_printed

string

HS code your supplier printed on the invoice. Set to have the classifier compare and flag disagreements.

confidence_threshold

number (0 to 1)

Minimum confidence before needs_review is false. Defaults to 0.85.

Request body (batch)

lines

ClassifyLine[]Required

1 to 50 line objects: { description, hs_code_printed? }.

destination_country

string (ISO-2)Required

Destination country shared by all lines.

confidence_threshold

number

Applied per-line.

Response 200 (single)

hs_6_code

string

6-digit HS heading.

Example: 851762

recommended_10_digit

string

10-digit HTS code when the destination has a national schedule (US, CA).

Example: 8517.62.00.90

confidence

number

0 to 1. Compare against confidence_threshold to decide needs_review.

reason

string

Prose explanation of why this code was chosen.

needs_review

boolean

True when confidence is below threshold or hs_code_printed disagrees.

candidates

array

Top-N alternative codes with scores.

disagreement_with_printed

boolean

True when hs_code_printed differs from the recommendation.

Response 200 (batch)

results

ClassificationResult[]

Per-line result in the input order.

needs_review

int[]

Indices of results that need human review.

consistency

object

common_chapter + outlier_indices for shipments where most lines share a chapter and a few outliers do not.

Example request

curl https://www.landedfees.com/api/v1/classify \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Wireless bluetooth earbuds with charging case",
  "destination_country": "US"
}'