# Customs Shipment Records API

Search customs shipment records by company, product, HS code and route, with ports, weight, quantity and value. 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.032 per customs shipment record

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

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

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `direction` | string | No | Whether to search import or export customs records. |
| `product` | array | No | Product keywords to search for in the shipment goods description. |
| `hsCode` | string | No | Customs tariff code to filter shipments, 4 or more digits. |
| `importer` | array | No | Importing company name to search for. |
| `exporter` | array | No | Exporting company name to search for. |
| `sourceCountries` | array | No | Search only these countries' customs datasets (for example america, mexico, india); leave empty to search all of them. Some countries have several datasets, e.g. the US has america, america_ship and america_stat. |
| `originCountry` | array | No | Origin countries to filter shipments by, as ISO 3166 alpha-3 codes (e.g. CHN, USA). Pick from the list; English country names are also accepted. |
| `destinationCountry` | array | No | Destination countries to filter shipments by, as ISO 3166 alpha-3 codes (e.g. CHN, USA). Pick from the list; English country names are also accepted. |
| `startDate` | date | No | Earliest shipment date to include, within the last three years. |
| `endDate` | date | No | Latest shipment date to include. |
| `maxResults` | integer | No | How many customs shipment records 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/shipments/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/shipments/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 |
|-------|--------------|------|
| `shipmentId` | Shipment ID | text |
| `date` | Date | date |
| `direction` | Direction | text |
| `importer` | Importer | text |
| `exporter` | Exporter | text |
| `hsCodes` | HS Codes | array |
| `goodsDescriptions` | Goods Descriptions | array |
| `productTags` | Product Tags | array |
| `originCountry` | Origin Country | text |
| `originCountryCode` | Origin Country Code | text |
| `destinationCountry` | Destination Country | text |
| `destinationCountryCode` | Destination Country Code | text |
| `departurePort` | Departure Port | text |
| `arrivalPort` | Arrival Port | text |
| `transportMode` | Transport Mode | text |
| `weightKg` | Weight (kg) | number |
| `quantity` | Quantity | number |
| `quantityUnit` | Quantity Unit | text |
| `valueUsd` | Value (USD) | currency |
| `unitPricePerKgUsd` | Unit Price per kg (USD) | currency |
| `unitPriceUsd` | Unit Price (USD) | currency |
| `billOfLading` | Bill of Lading | text |