> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindcase.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

`POST /v1/data/customs/companies/run`

**Pricing:** $0.04 per companie ($38.00 per 1,000).

## Request

Send the inputs under `params`. Only the keys below are accepted; any other key returns `422 invalid_params`.

**product** `string[]`

Product keywords to match against customs goods descriptions.

**hsCode** `string`

Customs HS code (4 or more digits) to anchor the trade query.

**direction** `string` (default: importers)

Which side of the trade to rank: importing companies or exporting companies.

Allowed values: `importers` (Importers), `exporters` (Exporters).

**counterpartyName** `string`

Name of the trading partner company on the other side of the shipments, used to narrow the ranking.

**originCountries** `string[]`

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.

248 allowed values, for example `AFG` (Afghanistan), `ALA` (Aland Islands), `ALB` (Albania), `DZA` (Algeria), `ASM` (American Samoa), `AND` (Andorra), `AGO` (Angola), `AIA` (Anguilla), `ATA` (Antarctica), `ATG` (Antigua and Barbuda). Fetch the full list with `GET /v1/data/customs/companies?expand=options`.

**destinationCountries** `string[]`

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.

248 allowed values, for example `AFG` (Afghanistan), `ALA` (Aland Islands), `ALB` (Albania), `DZA` (Algeria), `ASM` (American Samoa), `AND` (Andorra), `AGO` (Angola), `AIA` (Anguilla), `ATA` (Antarctica), `ATG` (Antigua and Barbuda). Fetch the full list with `GET /v1/data/customs/companies?expand=options`.

**maxResults** `integer` (default: 50)

How many companies to return in total. Defaults to 50; use 0 for all.

Max `100`.

## Example

```bash cURL theme={null}
curl -X POST "https://api.mindcase.co/v1/data/customs/companies/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "hsCode": "0901",
    "originCountries": [
      "COL"
    ],
    "direction": "importers",
    "maxResults": 5
  }
}'
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://api.mindcase.co/v1/data/customs/companies/run",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"},
    json={"params": {
    "hsCode": "0901",
    "originCountries": [
        "COL"
    ],
    "direction": "importers",
    "maxResults": 5
}},
)
job = r.json()
rows = job.get("data", [])  # if job["status"] == "running", poll /v1/jobs/{job_id}/results
```

```javascript Node.js theme={null}
const r = await fetch("https://api.mindcase.co/v1/data/customs/companies/run?wait=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {
  "hsCode": "0901",
  "originCountries": [
    "COL"
  ],
  "direction": "importers",
  "maxResults": 5
} }),
});
const job = await r.json();
const rows = job.data ?? []; // if job.status === "running", poll /v1/jobs/{job_id}/results
```

## Response fields

Each row in `data` is one companie, keyed by these fields.

| Field | 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 |

## Example response

Abridged: long text and lists are shortened.

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "customs/companies",
  "status": "completed",
  "row_count": 1,
  "truncated": false,
  "data": [
    {
      "avgQuantityUnitPriceUsd": 88.2724,
      "quantity": 30773,
      "tradeCount": 2691,
      "companyName": "SMART AND FINAL DEL NOROESTE",
      "avgWeightUnitPriceUsd": 17.2826,
      "country": "MEX",
      "weightKg": 157175.63,
      "valueUsd": 2716407.17
    }
  ]
}
```

## Related APIs

For the individual shipments use [`customs/shipments`](https://docs.mindcase.co/apis/customs/shipments); for aggregate country-level trade use [`customs/trade-stats`](https://docs.mindcase.co/apis/customs/trade-stats).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.