# US Import Data API - ImportYeti Bill of Lading and Suppliers (`nabeelbaghoor/us-import-bill-of-lading-data-api`) Actor

US customs import data from the ImportYeti API: search bills of lading with PowerQuery, rank top US importers and overseas suppliers, pull company and supplier profiles, BOL lists and lookups, and find suppliers or buyers by product, HS code, port and country. Bring your own key.

- **URL**: https://apify.com/nabeelbaghoor/us-import-bill-of-lading-data-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Business, Lead generation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 company or supplier search match returneds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## US Import Data API - ImportYeti Bill of Lading and Suppliers

Pull US customs import data from the official ImportYeti Data API: bills of lading, top US importers and overseas suppliers, company and supplier profiles and product rankings, as clean dataset rows, with your own ImportYeti key.

Bring your own API key. This actor calls only ImportYeti's own documented REST API on `data.importyeti.com`. It does not scrape importyeti.com.

### What it does

- **PowerQuery shipment search**: search US import bills of lading by product description, HS code, US company, overseas supplier, supplier country, US port of entry, foreign port, vessel, carrier, container, notify party, weight, TEU, BOL type and date range, with AND, OR, NOT, phrases, wildcards and ranges.
- **Top US importers and top overseas suppliers**: the same filters, ranked by shipment volume or weight, with addresses, websites, phones, ports and HS codes for each company.
- **Company and supplier search**: find a US importer or an overseas supplier by name, phone or website and get its ImportYeti slug, address, total shipments, most recent shipment and top trading partners.
- **Company and supplier profiles**: the full ImportYeti profile for each slug: aliases, addresses, website, phone, total shipments, date range, carriers, containers, HS codes, trade lanes, time series, supplier or customer table, recent BOLs and shipping cost.
- **BOL lists**: every bill of lading number of a US company or a supplier in a date range, optionally opened into full bills of lading.
- **Bill of lading lookup**: one full US import BOL per number, with about 100 fields: shipper, consignee, notify party, contacts, ports, product, HS code, weight, TEU, vessel, carrier and containers.
- **Product rankings**: suppliers and US buyers ranked by how specialised they are in a product keyword, filtered by supplier country.
- Flat columns for spreadsheets, plus the complete ImportYeti record under `record` for every row.
- Not found slugs, unknown BOL numbers, empty searches and refused requests come back as one free row with `found: false` and a note.

### How to get an ImportYeti API key

1. Create an account on importyeti.com and buy data credits (the API runs on prepaid data credits).
2. Open My Account, Settings, API Credits Settings. Your API key and remaining credit balance are shown there.
3. Paste the key into the **API key** field of this actor, or set it as the `DATA_API_KEY` environment variable. It is sent only in the `IYApiKey` header.

ImportYeti charges data credits per call: company and supplier search and the database date are free when you go on to open what you find, profiles cost 1 credit each, a BOL lookup 0.1 credit, and lists, product rankings and PowerQuery 1 credit per 10 records. If you use search on its own, ImportYeti bills it at 0.1 credit per record and may limit it until you ask support to switch billing on. Each run's log reports the credits ImportYeti says it used and the balance left.

### Input

| Field | Used by | What it does |
| --- | --- | --- |
| What to run | all | Picks one of the twelve modes. |
| Product description, Raw product description, HS code | PowerQuery | Text filters with AND, OR, NOT, parentheses, "phrases" and wildcards (at most one \* and three ?). |
| US company (slug), Overseas supplier (slug) | PowerQuery | Limit to one importer or supplier, such as `ikea-supply`. |
| Supplier country, US port of entry, Foreign port of lading, Last visited foreign port, Notify party, Vessel name, Carrier (SCAC), Container ID | PowerQuery | Exact or wildcard filters on the bill of lading. |
| BOL type | PowerQuery | R regular (carrier filed) or H house (forwarder filed). |
| Weight, TEU, Company and Supplier total shipments | PowerQuery | Ranges such as `[1000 TO 15000]` or `[10 TO *]`. |
| Company phone, Company email, Internal supplier, Include records with no consignee or shipper | PowerQuery | Contact and relationship filters. |
| Rank by | Top importers, Top suppliers | Shipment count (default) or weight. |
| Start date, End date | PowerQuery, BOL lists | YYYY-MM-DD or mm/dd/yyyy. ImportYeti defaults to 01/01/2021 through the end of last month. |
| Company or supplier name, Phone number, Website | Search modes | At least one is needed. |
| Slugs | Profiles, BOL lists | One slug per line, or a search key such as `company/walmart`, or an importyeti.com URL. |
| Open each bill of lading | BOL lists | Turns each BOL number into a full bill of lading row. |
| BOL numbers | BOL lookup | One number per line. |
| Product keyword, Supplier countries, Exclude supplier countries | Product modes | The product and the supplier country filter. |
| Maximum rows | all | Stops the run after this many rows (default 20). |
| Requests per minute | all | Optional pacing. |
| API key | all | Your ImportYeti key. |

### Example output

One PowerQuery shipment search row (illustrative values, field names as ImportYeti documents them; `record` is shortened):

```json
{
  "mode": "shipmentSearch",
  "found": true,
  "recordType": "bill_of_lading",
  "input": "product_description=furniture",
  "name": "Poliform Usa Inc",
  "slug": "poliform-usa",
  "bolNumber": "CCLLMILS17011590",
  "arrivalDate": "08/21/2017",
  "companyName": "Poliform Usa Inc",
  "supplierName": "Poliform Spa",
  "supplierCountry": "Italy",
  "productDescription": "Kitchen Furniture Bedroom Furniture Living Room Furniture",
  "hsCode": "940340",
  "entryPort": "Newark, Nj",
  "exitPort": "Genova",
  "weight": 1327,
  "teu": 1,
  "vesselName": "Seaspan Chiba",
  "carrier": "CCLL - Cargo Container Line Limited",
  "country": "United States",
  "countryCode": "US",
  "totalShipments": 2066,
  "partners": "Poliform Usa Inc",
  "phone": "+12124211600",
  "position": 1,
  "totalMatches": 1000,
  "note": null,
  "record": { "bol_number": "CCLLMILS17011590", "bol_type": "H", "master_bol_number": "NYKSMILT12616400", "containers": [ { "id": "NYKU3438730", "type": "22G0" } ] },
  "retrievedAt": "2026-10-20T09:00:00.000Z"
}
```

A top US importers row fills `name`, `slug`, `address`, `website`, `phone`, `totalShipments`, `matchingShipments`, `entryPort`, `exitPort`, `hsCode`, `weight` and `teu`. A product ranking row fills `name`, `slug`, `matchingShipments`, `specialization`, `productDescription` and `partners`.

### Pricing

Pay per event, only for rows that carry ImportYeti data. Not found, empty and refused rows are free.

| Event | Price |
| --- | --- |
| Company or supplier search match | $0.005 |
| Bill of lading number listed | $0.005 |
| Bill of lading returned (lookup, opened list entry, PowerQuery shipment) | $0.01 |
| Ranked importer or supplier (product or PowerQuery ranking) | $0.01 |
| Company or supplier profile | $0.02 |

ImportYeti data credits are billed separately by ImportYeti on your own account.

### FAQ

#### Is this the official ImportYeti API?

Yes. The actor calls the ImportYeti Data API at data.importyeti.com, the same versioned `/v1.0` REST API described on docs.importyeti.com, with your own key. It is not affiliated with or endorsed by ImportYeti.

#### What data does ImportYeti cover?

ImportYeti compiles US Customs vessel manifests (bills of lading for ocean imports into the United States), matches them to US importers and overseas suppliers, and adds contacts, HS codes, ports, carriers and container details. ImportYeti's API also covers US exports and Mexico customs declarations; this actor wraps the US import routes.

#### How do I find a company's suppliers?

Run Search US companies with the company name, copy the `slug` of the right match, then run US company profiles (the supplier table) or PowerQuery top overseas suppliers with that slug in US company (slug).

#### How do I find US buyers for a product?

Use US buyers ranked by product with a product keyword for specialised buyers, or PowerQuery top US importers with a product description or HS code for the biggest buyers by volume.

#### How is this different from an ImportYeti scraper?

Scrapers read importyeti.com pages, which ImportYeti's Terms of Service s.6.2 forbids for automated retrieval. This actor uses the paid API that ImportYeti sells for programmatic access, so results come from documented JSON fields and the run uses your own credits.

#### What happens if my key is missing, wrong or out of credits?

The run ends cleanly with a status message saying what to fix: a missing key, a key ImportYeti rejects (HTTP 401), an empty credit balance (HTTP 403 Not enough credits) or a search limit on the account.

#### How do I keep costs down?

Keep Maximum rows small while you tune filters, use the search modes to get slugs before opening profiles, and leave Open each bill of lading off unless you need full BOLs.

### Licensing note

ImportYeti's Terms of Service (effective 2026-08-21) call data delivered through the API "Purchased Data" (s.5.1) and give a perpetual, irrevocable covenant not to sue over its use, "including modification, publication, distribution, and resale" (s.5.2), with no audit, reporting or field of use restriction (s.5.3); you may keep the data after your subscription ends. Bulk delivery of the full database or a continuous feed is not Purchased Data (s.5.1), and the Services may not be used to copy ImportYeti's database or build a substitute for it (s.6.2). Login credentials may not be shared (s.2.3). Use your own key and check the current Terms and Data Use Policy on importyeti.com before relying on this.

### Keywords

US import data API, bill of lading API, US customs data, ImportYeti API, import records, supplier search, find suppliers, US importers list, shipment data, trade data API, HS code search, PowerQuery, freight and container data, sourcing intelligence, lead generation for importers.

# Actor input Schema

## `mode` (type: `string`):

PowerQuery shipment search returns US import bills of lading that match your filters. Top US importers and Top overseas suppliers rank companies by shipment volume under the same filters. Search modes find a company or supplier and return its slug. Profile modes return the full ImportYeti profile for each slug. BOL list modes list the bills of lading of a company or supplier. Bill of lading lookup opens BOLs by number. Product modes rank suppliers or US buyers by how specialised they are in a product.

## `productDescription` (type: `string`):

PowerQuery modes. Words in the cleaned product description. Supports AND, OR, NOT, parentheses, "exact phrases" and wildcards (at most one \* and three ?), such as (sofa OR couch) AND NOT leather. Separate words without an operator are OR.

## `productDescriptionRaw` (type: `string`):

PowerQuery modes. Searches the original shipment wording, which keeps punctuation, codes and container text. Same operators as the product description.

## `hsCode` (type: `string`):

PowerQuery modes. HS code filter with operators and wildcards, such as 9403\* or 7013\* AND NOT (701391 OR 701341).

## `pqCompany` (type: `string`):

PowerQuery modes. Limit to one US importer by its ImportYeti slug, such as ikea-supply. The company search mode returns slugs.

## `pqSupplier` (type: `string`):

PowerQuery modes. Limit to one overseas supplier by its ImportYeti slug, such as poliform.

## `supplierCountry` (type: `string`):

PowerQuery modes. Supplier country name as ImportYeti stores it, such as China or (Vietnam OR Cambodia). The value list countries on importyeti.com shows the exact names.

## `entryPort` (type: `string`):

PowerQuery modes. US port of entry, such as Newark, Nj or Los Angeles\*. Operators and wildcards work.

## `exitPort` (type: `string`):

PowerQuery modes. The foreign port the shipment left from, such as Genova or Yantian. Operators and wildcards work.

## `lastVisitedForeignPort` (type: `string`):

PowerQuery modes. The last foreign port the vessel called at before the US. Operators and wildcards work.

## `notifyParty` (type: `string`):

PowerQuery modes. Notify party name on the bill of lading, often the customs broker or forwarder. Operators and wildcards work.

## `vesselName` (type: `string`):

PowerQuery modes. Vessel name, such as Seaspan Chiba. Operators and wildcards work.

## `carrierScacCode` (type: `string`):

PowerQuery modes. Ocean carrier as ImportYeti names it, such as Oney or MAEU.

## `containerId` (type: `string`):

PowerQuery modes. Container number, such as GCXU6148826. Operators and wildcards work.

## `bolType` (type: `string`):

PowerQuery modes. Regular carrier bills, house bills filed by a forwarder, or both.

## `weight` (type: `string`):

PowerQuery modes. Shipment weight range, such as \[1000 TO 15000] or \[20000 TO \*].

## `teu` (type: `string`):

PowerQuery modes. Twenty foot equivalent units per shipment, such as \[1 TO 4].

## `companyTotalShipments` (type: `string`):

PowerQuery modes. Lifetime shipment count of the US importer, such as \[10 TO 500] to find small and mid sized buyers.

## `supplierTotalShipments` (type: `string`):

PowerQuery modes. Lifetime shipment count of the supplier, such as \[\* TO 500].

## `companyPhone` (type: `string`):

PowerQuery modes. US importer phone number. Wildcards work, such as 1212\*.

## `companyEmail` (type: `string`):

PowerQuery modes. US importer email. Wildcards work, such as \*@example.com.

## `internalSupplier` (type: `string`):

PowerQuery modes. Whether the supplier is part of the same group as the importer.

## `includeOmittedData` (type: `boolean`):

PowerQuery modes. Also return shipments whose consignee or shipper was left empty or kept confidential on the manifest.

## `sortBy` (type: `string`):

Top US importers and Top overseas suppliers. How the ranked list is ordered, descending.

## `startDate` (type: `string`):

PowerQuery and BOL list modes. Earliest arrival date, as YYYY-MM-DD or mm/dd/yyyy. Leave empty for ImportYeti's default of 01/01/2021.

## `endDate` (type: `string`):

PowerQuery and BOL list modes. Latest arrival date, as YYYY-MM-DD or mm/dd/yyyy. Leave empty for ImportYeti's default, the last day of the previous month.

## `searchName` (type: `string`):

Search modes. Name to look for, such as Walmart or Foxconn. Give a name, a phone number or a website.

## `searchPhone` (type: `string`):

Search modes. Phone number to look for.

## `searchWebsite` (type: `string`):

Search modes. Website to look for, such as walmart.com.

## `slugs` (type: `array`):

Profile and BOL list modes. One ImportYeti slug per line, up to 500 a run, such as walmart or ikea-supply. A search key (company/walmart) or an importyeti.com company or supplier URL also works.

## `fetchFullBols` (type: `boolean`):

BOL list modes. Off returns BOL numbers only. On opens each listed BOL (one more request and 0.1 ImportYeti credit each) and returns the shipper, consignee, ports, product, HS code, weight, vessel and containers.

## `bolNumbers` (type: `array`):

Bill of lading lookup. One US import bill of lading number per line, up to 1,000 a run.

## `product` (type: `string`):

Product modes. Product keyword, such as furniture or bluetooth speaker. Suppliers and US buyers are ranked by how specialised they are in it.

## `countries` (type: `array`):

Product modes. Only suppliers from these countries, one country name per line, such as china, india or brazil.

## `excludeCountries` (type: `array`):

Product modes. Leave out suppliers from these countries, one country name per line.

## `maxResults` (type: `integer`):

Stop after this many rows. Each page of up to 50 records and each profile or BOL spends ImportYeti data credits, so start small.

## `requestsPerMinute` (type: `integer`):

Optional pacing ceiling. ImportYeti publishes no fixed rate limit but throttles sustained heavy use.

## `apiKey` (type: `string`):

Your ImportYeti API key, from My Account, Settings, API Credits Settings on importyeti.com. Sent only in the IYApiKey header. Falls back to the DATA_API_KEY environment variable.

## Actor input object example

```json
{
  "mode": "shipmentSearch",
  "productDescription": "bluetooth speaker",
  "bolType": "",
  "internalSupplier": "",
  "includeOmittedData": false,
  "sortBy": "",
  "fetchFullBols": false,
  "maxResults": 20,
  "requestsPerMinute": 30
}
```

# Actor output Schema

## `records` (type: `string`):

One row per record returned for the chosen mode.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "productDescription": "bluetooth speaker"
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/us-import-bill-of-lading-data-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "productDescription": "bluetooth speaker" }

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/us-import-bill-of-lading-data-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "productDescription": "bluetooth speaker"
}' |
apify call nabeelbaghoor/us-import-bill-of-lading-data-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/us-import-bill-of-lading-data-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/D47epuc1zHCQv5fCU/builds/c62KixuBA2kcltxGL/openapi.json