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

`POST /v1/data/customs/shipments/run`

**Pricing:** $0.03 per customs shipment record ($32.00 per 1,000).

## Request

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

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

Whether to search import or export customs records.

Allowed values: `imports` (Imports), `exports` (Exports).

**product** `string[]`

Product keywords to search for in the shipment goods description.

**hsCode** `string`

Customs tariff code to filter shipments, 4 or more digits.

**importer** `string[]`

Importing company name to search for.

**exporter** `string[]`

Exporting company name to search for.

**sourceCountries** `string[]`

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.

165 allowed values, for example `afghanistan` (Afghanistan), `africa_bol` (Africa BOL), `america` (America BOL), `america_ship` (America Master BOL), `america_stat` (America STAT), `angola` (Angola), `angola_stat` (Angola STAT), `argentina` (Argentina), `argentina_bol` (Argentina BOL), `argentina_un_stat` (Argentina STAT). Fetch the full list with `GET /v1/data/customs/shipments?expand=options`.

**originCountry** `string[]`

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.

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/shipments?expand=options`.

**destinationCountry** `string[]`

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.

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/shipments?expand=options`.

**startDate** `date`

Earliest shipment date to include, within the last three years.

**endDate** `date`

Latest shipment date to include.

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

How many customs shipment records to return in total. Defaults to 50; use 0 for all.

Max `500`.

## Example

```bash cURL theme={null}
curl -X POST "https://api.mindcase.co/v1/data/customs/shipments/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "direction": "exports",
    "exporter": [
      "Dr Reddys Laboratories"
    ],
    "destinationCountry": [
      "USA"
    ],
    "startDate": "2026-12-17",
    "endDate": "2027-12-16",
    "maxResults": 5
  }
}'
```

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

r = requests.post(
    "https://api.mindcase.co/v1/data/customs/shipments/run",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"},
    json={"params": {
    "direction": "exports",
    "exporter": [
        "Dr Reddys Laboratories"
    ],
    "destinationCountry": [
        "USA"
    ],
    "startDate": "2026-12-17",
    "endDate": "2027-12-16",
    "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/shipments/run?wait=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {
  "direction": "exports",
  "exporter": [
    "Dr Reddys Laboratories"
  ],
  "destinationCountry": [
    "USA"
  ],
  "startDate": "2026-12-17",
  "endDate": "2027-12-16",
  "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 customs shipment record, keyed by these fields.

| Field | 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 |
| `declarationNumber` | Declaration Number | text |
| `dataSource` | Data Source | text |

## Example response

Abridged: long text and lists are shortened.

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "customs/shipments",
  "status": "completed",
  "row_count": 1,
  "truncated": false,
  "data": [
    {
      "direction": "exports",
      "billOfLading": "MAEU271193074",
      "originCountryCode": "IND",
      "productTags": [
        "DOXYCYCLINE FOR INJECTION"
      ],
      "weightKg": 340,
      "transportMode": null,
      "importer": "DR. REDDY'S LABORATORIES, INC",
      "quantityUnit": "PKG",
      "unitPricePerKgUsd": null,
      "declarationNumber": null,
      "destinationCountry": "United States",
      "exporter": "DR REDDYS LABORATORIES LTD SEZ FTO",
      "dataSource": "maritime_silk_bol",
      "goodsDescriptions": [
        "DOXYCYCLINE FOR INJ USP"
      ],
      "unitPriceUsd": null,
      "destinationCountryCode": "USA",
      "originCountry": "India",
      "valueUsd": null,
      "hsCodes": null,
      "date": "2026-07-14",
      "quantity": 5,
      "shipmentId": "6ac76b7ddf58c25ce0426763",
      "arrivalPort": null,
      "departurePort": null
    }
  ]
}
```

## Related APIs

For ranked importers and exporters of a product use [`customs/companies`](https://docs.mindcase.co/apis/customs/companies); for aggregate trade by HS code or country 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.