Companies
GET

Search US companies by name, phone, or website

Free

Find US importers and resolve a display name to an ImportYeti URL slug. Search is not charged separately when you then call the corresponding data endpoint — see Credits. Provide at least one of name, phone, or website.

Related:Find a company's suppliersCore concepts

Parameters#

Query parameters

  • page_sizenumberoptionaldefault 10

    Number of returned results

  • offsetnumberoptionaldefault 0

    Results starting position

  • namestringoptional
  • phonestringoptional
  • websitestringoptional
  • fieldsstringoptional

    Comma-separated list of response fields to keep on each returned record. Every other field on the record is omitted. Names the record does not have are ignored. The envelope (requestCost, creditsRemaining, executionTime, totalCount) is always returned in full. Cannot be combined with exclude. Leave this out for the full record.

  • excludestringoptional

    Comma-separated list of response fields to drop from each returned record. Every other field is kept. Cannot be combined with fields. Leave this out for the full record.

  • formatstringoptionaldefault json

    Response encoding. Defaults to json. Pass toon to receive TOON — the same data in a compact, token-efficient text form intended for LLM prompts. Error responses are always JSON.

    one ofjsontoon

fields, exclude, and format work the same way on every endpoint — Response shaping has worked examples.

Response#

A list of matching US companies. Use the slug from each result’s key on later calls — not the display name.

Response shape
{
  "requestCost": 0,
  "creditsRemaining": 9998.5,
  "data": [
    {
      "title": "Walmart",
      "countryCode": "US",
      "type": "company",
      "address": "601 N Walton Blvd, Bentonville, Ar 72712, Us",
      "totalShipments": 442496,
      "mostRecentShipment": "29/03/2024",
      "topSuppliers": ["Damco India", "Hangzhou Greatstar Industrial", "Bestway Hong Kong International L Imited", "Just Play Hk"],
      "key": "company/walmart"
    }
  ],
  "executionTime": "224ms"
}

Top-level fields#

  • data — an array of matching records
  • requestCost — Data credits used for this call (0 if none)
  • creditsRemaining — Your data credit balance after the call
  • executionTime — How long the request took

Fields on each item in data#

FieldExample
  • titlestringWalmart
  • countryCodestringUS
  • typestringcompany
  • addressstring601 N Walton Blvd, Bentonville, Ar 72712, Us
  • totalShipmentsnumber442496
  • mostRecentShipmentstring29/03/2024
  • topSuppliersstring[]["Damco India", "Hangzhou Greatstar Industrial", "Bestway Hong Kong International L Imited", "Just Play Hk"]
  • keystringcompany/walmart

Errors#

Failures come back as JSON with a statusCode and message. The ones worth handling here are 401 (bad or missing key), 403 (out of credits), and 404 (no such record). See all error responses.