How to pull a company's customs import-export records with an API

Company names on customs filings are messy — the same buyer can appear as "ACME INC", "Acme Incorporated" and "ACME INC.". Querying the raw user input gives poor recall, so first resolve the name or domain to a canonical entity.

• Prefer a domain as input, then the full legal name, and only then a short name.
• Store the entity ID once resolved and query by ID from then on.
• When several entities share a name, disambiguate by country and industry.

With the entity resolved, fetch customs records by role (consignee or shipper). Constrain the first call to a window such as the last 12 months, confirm the field shape and volume, then backfill history.

Typical fields include shipper, consignee, HS code, product description, quantity, value, origin port, destination port, carrier and bill date.

Raw shipments aren't the insight. The useful layer is aggregate: which HS codes dominate, who the top five suppliers are, whether purchase frequency is rising, and whether the account recently switched suppliers. Those signals decide whether to pursue the account and how to open.

• Group by HS code to get the category mix.
• Group by counterparty to get the incumbent supplier list.
• Group by month to expose trend and seasonality.

• Coverage varies by country: the US, India and Vietnam have the richest bill-of-lading data, while some European markets only publish aggregates.
• Don't treat the value field as a transaction price — it's a declared value.
• For incremental sync, use the timestamp in the response rather than local time.