Pre-shipment Validation API

Quickstart

1. 1
   Sign in to ClassifyHQ and visit Team Settings. Scroll to API Keys and click Generate key. The plaintext key (prefixed ck_live_…) is shown once — copy it immediately.
2. 2
   Send your first 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"}'

3. 3
   Inspect data.verdict in the JSON response. On warn or fail, walk data.findings[] for the rules that fired and act accordingly — block the shipment, surface a warning to ops, or pass through.

Authentication

Every request to /api/validate must carry a valid API key. The middleware accepts any of three forms:

Keys are scoped to a single team and are stored only as SHA-256 hashes after generation — ClassifyHQ cannot retrieve a plaintext key after creation. Lost keys must be revoked and replaced. Revoke from the same Team Settings page; revocation takes effect immediately and subsequent calls return 401.

Endpoint

Request body must be application/json. All checks are deterministic; no LLM calls are made. Typical p95 latency is under 30 ms.

Request body

Response shape

All successful and warn responses use HTTP 200. A fail verdict uses HTTP 422 so naive integrations that only branch on status codes still get a clear signal. The body is always a JSON object with a top-level data envelope plus meta.

{
  "data": {
    "verdict": "warn",
    "input": {
      "hs_code": "6109100012",
      "origin_country": "CN",
      "destination_country": "US"
    },
    "matched_code": {
      "code": "610910",
      "description": "T-shirts, singlets and other vests; of cotton, knitted or crocheted"
    },
    "findings": [
      {"rule": "code_well_formed",     "result": "pass", "message": "Code is 10 digits.", "context": []},
      {"rule": "hs6_active",           "result": "pass", "message": "Matched HS6: T-shirts...", "context": []},
      {"rule": "country_code_active",  "result": "warn", "message": "Code is not a valid leaf in the US tariff schedule.", "context": []},
      {"rule": "description_match",    "result": "pass", "message": "Description hint matches chapter 61.", "context": []}
    ],
    "required_documents": [
      {"name": "Textile country of origin declaration", "reason": "CBP requires textile origin documentation per 19 CFR 102.21."}
    ],
    "evaluated_at": "2026-04-25T07:38:03+00:00"
  },
  "meta": {
    "api_version": "v1",
    "documentation": "https://classifyhq.ai/api/docs"
  }
}

matched_code is the most specific tariff line we resolved — the destination's country-specific code if the leaf was found, otherwise the HS6 prefix. matched_code is null when no HS6 prefix could be matched at all.

Verdict semantics

Verdict is a roll-up across all findings: any fail finding produces fail; otherwise any warn produces warn; otherwise pass.

Rule reference

Each finding is tagged with a rule identifier so you can branch on specific signals (e.g. block on code_well_formed.fail, alert on country_pair_trap.warn, and pass through everything else).

required_documents is returned alongside the findings as a separate field (not as rule findings). It lists the customs documents typically required for the origin/destination/chapter combination — e.g. Lacey Act for chapter 44 wood, textile country-of-origin declaration for chapters 61–63 into the US.

Errors

Integration patterns

Shopify webhook on order creation

Subscribe to orders/create. For every line item, look up the SKU's HS code in your metafields and call /api/validate. On fail, post a Slack alert to ops; on warn, write a tag to the order so customer service sees it before fulfilment.

Pre-booking gate from your TMS / ERP

Before pushing a shipment to Ingrid / ShipStation / your carrier, run each line through /api/validate. Block the booking on fail; surface warn findings in the booking UI so the operator can confirm.

Nightly catalog sweep

Iterate over your SKU catalog overnight. Persist any warn or fail findings to a reporting table; review the queue in the morning. Catches drift introduced by manual edits, broker overrides, or stale country tariff data.

// Node.js example — Shopify webhook handler
import express from 'express';
const app = express();

app.post('/webhooks/orders-create', express.json(), async (req, res) => {
  const order = req.body;
  for (const item of order.line_items) {
    const r = await fetch('https://classifyhq.ai/api/validate', {
      method: 'POST',
      headers: {
        'X-Api-Key': process.env.CLASSIFYHQ_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        hs_code: item.properties.hs_code,
        description: item.title,
        origin_country: item.origin_country,
        destination_country: order.shipping_address.country_code,
        declared_value: item.price,
        currency: order.currency,
      }),
    });
    const { data } = await r.json();
    if (data.verdict !== 'pass') {
      await alertOps(order.id, item.sku, data);
    }
  }
  res.status(200).end();
});

Versioning & rate limits

The current API version is v1, surfaced in meta.api_version. Breaking changes will increment the major version and run alongside the previous version for at least 90 days. Rate limit is 100 requests per minute per IP, shared with the public Tariff Reference API. If you need a higher limit, contact us.