# ImportYeti API — US import & customs bill-of-lading records: find which overseas factory manufactures for a US brand, and which US brands a factory ships to. Company and supplier lookup, supplier/customer rankings by shipment count, the underlying bills of lading with HS codes, product text, weight, containers and trade lanes, plus top importers and suppliers per HS code. Public logged-out data, no account.

> Search US importers and overseas suppliers by name. Returns the slug you feed to every other action, plus lifetime shipment count and the date of the most recent shipment for each hit.
> ReefAPI engine `importyeti` · 7 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/importyeti/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /importyeti/v1/search — 1 credit
Search US importers and overseas suppliers by name. Returns the slug you feed to every other action, plus lifetime shipment count and the date of the most recent shipment for each hit.

**Parameters:**
- `query` (string, required) — Company or supplier name to search for. Matches US importers and overseas suppliers by name; partial names work.
- `page` (integer, optional, default 1) — Result page, 10 results per page. The logged-out surface serves at most 14 pages (140 results) however large the reported total is — page 15 and beyond return nothing upstream, so they are rejected rather than answered empty.
- `type` (enum, optional) — Restrict results to one side of the trade. Omit for both. [one of: company, supplier]

**Returns:** results[] (name, kind, slug, url, address, country_code, total_shipments, last_shipment_date, other_addresses_count, other_names_count), page, page_size, total_hits, total_hits_is_floor, total_pages_claimed, max_page, results_cap, reachable_results, has_more, next_page. The source's total_pages_claimed over-states what it will serve — results_cap (140) is the measured truth.

**Example request body:**
```json
{
  "query": "nike"
}
```

### POST /importyeti/v1/company — 3 credits
Full report for a US importer: profile and totals, its overseas suppliers ranked by shipments, its most recent bills of lading, HS-code breakdown, trade lanes, carriers and container mix. One call; you do not also need `suppliers` and `shipments` for the same company.

**Parameters:**
- `company` (string, required) — The US importer: its ImportYeti slug (`nike-usa`), the path or URL of its page (`/company/nike-usa`), or a plain company name to resolve through search (costs one extra upstream request; the row picked is reported as `resolved_from`).

**Returns:** subject{}, suppliers[] (ranked), shipments[], shipments_with_declared_value[], hs_codes[], trade_lanes[], carriers[], containers[], database_updated, truncated flags.

**Example request body:**
```json
{
  "company": "nike-usa"
}
```

### POST /importyeti/v1/supplier — 3 credits
Full report for an overseas supplier: profile and totals, its US customers ranked by shipments, its most recent bills of lading, HS-code breakdown, trade lanes, carriers and container mix.

**Parameters:**
- `supplier` (string, required) — The overseas supplier: its ImportYeti slug (`apl-logistics-vietnam`), the path or URL of its page, or a plain name to resolve through search (costs one extra upstream request).

**Returns:** subject{}, customers[] (ranked), shipments[], shipments_with_declared_value[], hs_codes[], trade_lanes[], carriers[], containers[], database_updated, truncated flags.

**Example request body:**
```json
{
  "supplier": "apl-logistics-vietnam"
}
```

### POST /importyeti/v1/suppliers — 3 credits
Who manufactures for this US brand. The overseas suppliers of one US importer, ranked by the number of shipments between the two, with country, HS chapters and the product text from those shipments.

**Parameters:**
- `company` (string, required) — The US importer: its ImportYeti slug (`nike-usa`), the path or URL of its page (`/company/nike-usa`), or a plain company name to resolve through search (costs one extra upstream request; the row picked is reported as `resolved_from`).
- `limit` (integer, optional) — Trim the returned list. The logged-out surface publishes at most 50 rows whatever you pass, so this only makes the response smaller — it never reaches further back.
- `country_code` (string, optional) — Keep only counterparties in this ISO-2 country (applied by this API to the top-50 the source publishes, not by the source — so it filters that list, it does not search deeper than it).

**Returns:** subject{}, suppliers[] (rank, name, slug, country, shipments, shipments_last_12m, weight_kg, teu, hs_chapters[], product_descriptions), count, truncated, source_cap.

**Example request body:**
```json
{
  "company": "nike-usa"
}
```

### POST /importyeti/v1/customers — 3 credits
Who this factory ships to. The US importers buying from one overseas supplier, ranked by the number of shipments between the two.

**Parameters:**
- `supplier` (string, required) — The overseas supplier: its ImportYeti slug (`apl-logistics-vietnam`), the path or URL of its page, or a plain name to resolve through search (costs one extra upstream request).
- `limit` (integer, optional) — Trim the returned list. The logged-out surface publishes at most 50 rows whatever you pass, so this only makes the response smaller — it never reaches further back.
- `country_code` (string, optional) — Keep only counterparties in this ISO-2 country (applied by this API to the top-50 the source publishes, not by the source — so it filters that list, it does not search deeper than it).

**Returns:** subject{}, customers[] (rank, name, slug, country, shipments, shipments_last_12m, weight_kg, teu, hs_chapters[], product_descriptions), count, truncated, source_cap.

**Example request body:**
```json
{
  "supplier": "apl-logistics-vietnam"
}
```

### POST /importyeti/v1/shipments — 3 credits
The bills of lading behind a company or a supplier: date, counterparty, product description, weight, container and package counts, trade lane, and the declared CIF value where the manifest carries one. Pass either `company` or `supplier`.

**Parameters:**
- `company` (string, optional) — The US importer whose bills of lading to return. Pass this OR `supplier`, not both.
- `supplier` (string, optional) — The overseas supplier whose bills of lading to return. Pass this OR `company`, not both.
- `limit` (integer, optional) — Trim the returned list. The logged-out surface publishes at most 50 rows whatever you pass, so this only makes the response smaller — it never reaches further back.

**Returns:** subject{}, shipments[] (date, bill_of_lading, master/house bol, counterparty{}, product_description, weight_kg, containers, quantity, quantity_unit, shipping_route, estimated_shipping_cost_usd), shipments_with_declared_value[] (adds cif_value_usd), count, truncated, source_cap, date_range.

**Example request body:**
```json
{
  "company": "nike-usa"
}
```

### POST /importyeti/v1/hs_code — 3 credits
Trade in one HS code: the top US importers and the top overseas suppliers moving goods under it, ranked by shipments, plus recent bills of lading. Pairs with the `hs-code` engine — classify there, then find who actually ships it here.

**Parameters:**
- `hs_code` (string, required) — An HS chapter (2-digit, e.g. `61`), a 6-digit subheading (e.g. `610910`), or the full ImportYeti slug (`61-articles-of-apparel-and-clothing`). 2- and 6-digit codes are resolved against the site's own HS index; 4-digit headings are NOT listed in that index, so for those pass the slug, which every company/supplier response hands you in `hs_codes[].url`.
- `limit` (integer, optional) — Trim the returned list. The logged-out surface publishes at most 50 rows whatever you pass, so this only makes the response smaller — it never reaches further back.

**Returns:** hs_code, slug, url, description, top_importers[], top_suppliers[], shipments[], first_shipment_date, last_shipment_date, truncated, source_cap.

**Example request body:**
```json
{
  "hs_code": "61"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=importyeti
- Human docs page: https://reefapi.com/docs/importyeti
- Overview page: https://reefapi.com/importyeti-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt