ImportYeti API & Scraper
The ImportYeti API turns US customs bill-of-lading records into clean JSON in seven actions, and the question it exists to answer is who actually manufactures for a given brand.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
suppliers takes a US importer and returns its overseas suppliers ranked by the number of shipments between the two, each with the supplier's country, the HS chapters it ships under, the weight and TEU behind the relationship and the product text off those manifests. customers runs the same relationship in reverse: give it an overseas factory and it returns the US companies buying from it, ranked the same way, which is how you find a competitor's other clients. company and supplier return the full report for either side — lifetime shipment count, shipments in the last twelve months, first and last shipment date, alternate trading names, address, the HS-code breakdown, the trade lanes with their loading and discharge ports, the carriers by SCAC code and the container mix. shipments returns the bills of lading themselves: date, counterparty, product description, weight in kilograms, container count, package count and unit, trade lane, and the declared CIF value on the subset of manifests that carry one. search finds either side by name and hands back the slug every other action takes, with each hit's lifetime shipment count and the date of its most recent shipment. hs_code turns the relationship around a product instead of a company: give it an HS chapter or subheading and it returns the top US importers and the top overseas suppliers moving goods under it, which is how you build a supplier shortlist for a category you have classified but not yet sourced. This is public customs data about businesses, so the parties are named. The records run from 2015 to within about a week of the present, and every response carries the source's own database date so you are never guessing at freshness. No ImportYeti account, one ReefAPI key, and the standard { ok, data, meta, error } envelope.
How deep the public record goes, and where it stops
Every limit below was measured on 2026-09-23 across ten subjects, including one with 251,449 lifetime shipments. They are properties of the public record, not of this API, and every response states them in its own fields so a truncated list can never look complete.
| What you ask for | What comes back | The limit, stated |
|---|---|---|
| Suppliers of a company / customers of a supplier | Up to 50 counterparties, ranked by the shipments between the two parties | 50 is the ceiling on every subject, however large. truncated and source_cap say so on every response. |
| Shipments for a company or supplier | Up to 50 bills of lading, most recent first | Same 50-row ceiling. date_range returns the subject's true first and last shipment date, so you can see how much history sits behind the window. |
| Search | 10 results per page, up to 14 pages | 140 results is the hard ceiling. The record's own hit count runs far higher and saturates at 10,000; both the claimed figure and the reachable one come back, as total_hits and results_cap. |
| History | Records from 2015 to roughly a week before today | Measured: all eight company subjects began in January or February 2015 and ended within eight days of the run. database_updated carries the source's own cut-off date. |
| Declared shipment value | cif_value_usd on the manifests that carry one | A subset, returned as its own list rather than merged into the main one. The separate estimated_shipping_cost_usd is a freight model, present on about two thirds of shipments, and is named an estimate everywhere it appears. |
| HS codes | 2-digit chapters and 6-digit subheadings resolve from the code alone | 4-digit headings are not in the public HS index, so they take the slug instead — every company and supplier response hands you that slug in hs_codes[].url. |
About one counterparty row in ten has no name: US customs lets a shipper request confidentiality, and those manifests are aggregated under a placeholder. Those rows are returned rather than dropped, because deleting them would silently under-count the company, and each is flagged with name_withheld so you never rank a placeholder as if it were a factory.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/importyeti/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "nike"
}
}{
"ok": true,
"meta": {
"api": "importyeti",
"endpoint": "search",
"mode": "live",
"latency_ms": 693.9,
"record_count": 10,
"bytes": 2507,
"cache_hit": false,
"stop_reason": "max_pages",
"upstream_requests": 1,
"source_requests_remaining": 23,
"charged_credits": 1,
"version": "0.1.0"
},
"data": {
"results": [
{
"name": "Nike",
"name_withheld": false,
"kind": "company",
"slug": "nike",
"url": "/company/nike",
"address": "1 Bowerman Dr, Beaverton, Or 97005, Us",
"country_code": "US",
"total_shipments": 560,
"last_shipment_date": "2024-11-23",
"other_addresses_count": 25,
"other_names_count": 17
},
{
"name": "Nike",
"name_withheld": false,
"kind": "supplier",
"slug": "nike",
"url": "/supplier/nike",
"address": "Via Della Spiga 32 20121 Milano Mi Italy",
"country_code": "IT",
"total_shipments": 57,
"last_shipment_date": "2026-07-17",
"other_addresses_count": 2,
"other_names_count": 1
},
{
"name": "[redacted-name]",
"name_withheld": false,
"kind": "company",
"slug": "nike-usa",
"url": "/company/nike-usa",
"address": "Beaverton, Or 97005, Us",
"country_code": "US",
"total_shipments": 139964,
"last_shipment_date": "2026-09-16",
"other_addresses_count": 30,
"other_names_count": 24
}
],
"page": 1,
"page_size": 10,
"total_hits": 136,
"total_hits_is_floor": false,
"total_pages_claimed": 14,
"max_page": 14,
"results_cap": 140,
"reachable_results": 136,
"has_more": true,
"next_page": 2,
"query": "nike"
}
}What the ImportYeti API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | 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. | Pricing teams call search to search US importers and overseas suppliers by name. | query, page, type |
| company | 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. | Marketplace operators call company to get full report for a US importer. | company |
| supplier | 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. | Catalog enrichment teams call supplier to get full report for an overseas supplier. | supplier |
| suppliers | 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. | Retail analysts call suppliers to get who manufactures for this US brand. | company, limit, country_code |
| customers | Who this factory ships to. The US importers buying from one overseas supplier, ranked by the number of shipments between the two. | Pricing teams call customers to get who this factory ships to. | supplier, limit, country_code |
| shipments | 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`. | Marketplace operators call shipments to get the bills of lading behind a company or a supplier. | company, supplier, limit |
| hs_code | 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. | Catalog enrichment teams call hs_code to get trade in one HS code. | hs_code, limit |
Call search from your stack
curl -X POST https://api.reefapi.com/importyeti/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"nike"}'import requests
r = requests.post(
"https://api.reefapi.com/importyeti/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "nike"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/importyeti/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "nike"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.importyeti.search with {"query":"nike"}.Who uses this API and why
- Sourcing teams take a competitor's brand name and read suppliers to get its overseas factories ranked by shipment count, with the HS chapters and product text that say which factory makes which part of the range.
- Sales teams working a factory account call customers on that supplier to see which US companies already buy from it, ranked by volume, and size the account before the first call.
- Procurement shortlists start from hs_code: classify the product once, then read the top overseas suppliers already shipping that code into the US, with the shipment counts behind each one.
- Supply-chain risk and diligence tools track a supplier's concentration over time by reading a company's partner_countries breakdown and the twelve-month shipment counts next to each lifetime total.
- Competitive analysts watch shipments for movement: new counterparties appearing, trade lanes changing port, or a supplier's twelve-month count collapsing against its lifetime total.
Questions developers ask before integrating
What question does this actually answer that a company database does not?
Who ships to whom. A company database tells you a brand exists and roughly how big it is; this tells you that a named factory in Vietnam put 189 shipments on the water for that brand, under which HS codes, through which ports, and when the last one landed. It is the relationship between two businesses, read off the customs manifests that recorded it, and it runs in both directions — a brand's suppliers, and a factory's customers.
Where does the data come from, and is it legal to use?
US customs bill-of-lading manifests, which are public records, surfaced through ImportYeti. The parties in them are businesses — importers, exporters, freight forwarders and carriers — and the fields are the commercial terms of a shipment: names, addresses, dates, HS codes, weights, container counts and ports. It is business data about business activity, not personal data, which is why the companies are named.
How far back does it go, and how current is it?
Back to 2015 on every subject measured, and forward to within about a week of the present: on 2026-09-23 the most recent shipments across the sample were dated 15 and 16 September. Rather than asking you to trust that, every response returns database_updated with the source's own cut-off date, and each subject returns its true first_shipment_date and last_shipment_date.
Can I get more than 50 suppliers or more than 50 shipments?
Not on this API, and it will not pretend otherwise. The public record publishes a top 50 by shipment count and the 50 most recent bills of lading, and there is no deeper page behind them. Every response carries truncated and source_cap: 50, so a partial list is always labelled as one. What you can do is widen sideways — the 50 counterparties are the 50 that matter by volume, and each carries its own slug, so you can walk into any of them for its own full report.
Why do some rows have no company name?
Because the shipper asked US customs to keep it confidential, which is a right exporters can exercise. Those manifests are aggregated into a single placeholder row, and on large importers that row is sometimes the biggest one on the page. It is returned, not deleted — removing it would make the company's totals look smaller than they are — and it carries name_withheld: true plus no slug, so it can never be mistaken for a factory you could go and look up.
Is the shipping cost a real declared value?
Two different numbers, and the naming keeps them apart. cif_value_usd is a declared value and appears only on the manifests that actually carry one, in their own list. estimated_shipping_cost_usd is a freight model, not a customs figure; it was present on about two thirds of the shipments measured, and each subject also returns shipping_cost_coverage_pct saying what share of its shipments the model could price at all. Neither is a purchase price.
Does it cover exports, or trade between other countries?
No. This is US import records — goods arriving in the United States, mostly by sea. It will tell you which overseas factory ships to a US buyer and which US buyers a factory serves, but it does not cover US exports or trade that never touches a US port. That is a real boundary, and worth knowing before you plan around it.
I only have a company name, not an id. Does that work?
Yes. Pass the name and it is resolved for you, and the response reports which record it picked in resolved_from so you can pin the slug for later. The resolution is deliberately strict: the source's own search is fuzzy enough to return loosely related names for anything at all, so a name whose words the matched record does not carry comes back as NOT_FOUND rather than as a confident wrong company. Use search first when you want to choose between candidates yourself.
What is the ImportYeti API?
ImportYeti API is a ReefAPI endpoint group for us customs shipment records: which overseas factory ships to which us company, how often, and what it sends. It returns live JSON through POST requests under /importyeti/v1.
Is the ImportYeti API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. ImportYeti calls use the same shared credit balance as every other ReefAPI engine.
Do I need an ImportYeti login or account?
No login to ImportYeti is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the ImportYeti data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the ImportYeti API use?
ImportYeti actions currently cost 1-3 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call ImportYeti from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call importyeti actions with the same key, credit pool and JSON envelope used by normal REST requests.