# Customs Trade Companies API

Ranked lists of importing or exporting companies for a product or HS code, with aggregate trade weight, value and deal count. Covers customs filings and trade statistics from about 95 countries, including the United States, Mexico, Brazil, Colombia, India, Indonesia, Vietnam, Pakistan, Russia, Turkey, the UK and the EU.

**Pricing:** $0.038 per company

**Endpoint:** `POST /v1/data/customs/companies/run`

**Auth:** `Authorization: Bearer mk_live_...`

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `product` | array | No | Product keywords to match against customs goods descriptions. |
| `hsCode` | string | No | Customs HS code (4 or more digits) to anchor the trade query. |
| `direction` | string | No | Which side of the trade to rank: importing companies or exporting companies. |
| `counterpartyName` | string | No | Name of the trading partner company on the other side of the shipments, used to narrow the ranking. |
| `originCountries` | array | No | Origin countries to filter the trade records by, as ISO 3166 alpha-3 codes (e.g. COL, USA). Pick from the list; English country names are also accepted. |
| `destinationCountries` | array | No | Destination countries to filter the trade records by, as ISO 3166 alpha-3 codes (e.g. COL, USA). Pick from the list; English country names are also accepted. |
| `maxResults` | integer | No | How many companies to return in total. Defaults to 50; use 0 for all. |

## Example

`?wait=true` holds the request open until the run finishes (up to 60s) and returns the rows inline: one request, no polling.

```bash
curl -X POST "https://api.mindcase.co/v1/data/customs/companies/run?wait=true" \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{}}'
```

```python
import requests

resp = requests.post(
    "https://api.mindcase.co/v1/data/customs/companies/run",
    params={"wait": "true"},
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={"params": {}},
)
rows = resp.json()["data"]
```

## Longer runs

If the run is still going at the 60s ceiling you get back `{ job_id, status: "running" }` instead of rows (same if the result is over 100 rows; those come back `truncated`). Poll with that `job_id`:

```bash
# 1) check status
curl https://api.mindcase.co/v1/jobs/JOB_ID \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"

# 2) when status == completed, fetch the rows
curl https://api.mindcase.co/v1/jobs/JOB_ID/results \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"
```

Full API reference (auth, jobs, balance, SDKs, MCP): https://mindcase.co/skills.md

## Response columns

| Field | Display name | Type |
|-------|--------------|------|
| `companyName` | Company Name | text |
| `country` | Country | text |
| `weightKg` | Weight (kg) | number |
| `quantity` | Quantity | number |
| `valueUsd` | Value (USD) | currency |
| `avgWeightUnitPriceUsd` | Avg Unit Price (USD/kg) | currency |
| `avgQuantityUnitPriceUsd` | Avg Unit Price (USD/unit) | currency |
| `tradeCount` | Trade Count | integer |