/importyeti/companies

POST /api/importyeti/companies

Price: 20 credits

Get one business profile built from US ocean import bills of lading: identity and every alternative name and address it files under, geocoded location hierarchy, website, total and last-12-month shipment counts, estimated shipping spend, average TEU per shipment and per month, first and last shipment dates, the full month-by-month shipment history, HS and HTS commodity breakdowns, product keywords, container types and load types, carriers with SCAC codes and service types, bill types, origin countries, port-to-port trade lanes, notify parties, contact details, trademarks and the UFLPA forced-labour flag.

How to use it

The importer and counterparty id spaces are separate and about 40% of slugs exist in both, so the side must be named: a bare slug is rejected rather than guessed, and the qualified id comes from /importyeti/companies/search. This covers US ocean bills of lading only, so air and truck freight is absent rather than zero, and total_shipping_cost is ImportYeti's own freight estimate covering the share of shipments given by shipping_cost_coverage, never a declared customs value. A null phone is about as often a number the source published partly redacted as a business with none on file.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
• company string required — ImportYeti business id as returned by search: company/<slug> for a US importer or supplier/<slug> for a foreign counterparty. A full importyeti.com profile URL also works (examples: "company/nike-ihm", "supplier/kiefel", "https://www.importyeti.com/company/wal-mart"; minLength: 1)

Response

• @type string (default: "ImportyetiCompany")
• id string required
• alias string required
• role string required
• url string required
• name string nullable
• also_known_names array (default: [])
• address string nullable
• address_as_filed string nullable
• address_url string nullable
• address_shipments integer nullable
• country_code string nullable
• country string nullable
• country_url string nullable
• locations array (default: [])
  • @type string (default: "ImportyetiLocation")
  • name string nullable
  • location_type string nullable
  • latitude number nullable
  • longitude number nullable
  • url string nullable
• website string nullable
• other_websites array (default: [])
  • @type string (default: "ImportyetiWebsiteMention")
  • website string required
  • mentions integer nullable
• phone string nullable
• email string nullable
• total_shipments integer nullable
• shipments_12m integer nullable
• total_shipping_cost number nullable
• shipping_cost_coverage number nullable
• avg_teu_per_shipment object nullable
  • @type string (default: "ImportyetiTeuStats")
  • last_12m number nullable
  • last_24m number nullable
  • last_36m number nullable
  • prior_12_24m number nullable
  • prior_24_36m number nullable
• avg_teu_per_month object nullable
  • @type string (default: "ImportyetiTeuStats")
  • last_12m number nullable
  • last_24m number nullable
  • last_36m number nullable
  • prior_12_24m number nullable
  • prior_24_36m number nullable
• first_shipment_date string nullable
• last_shipment_date string nullable
• quarterly_growth_months array (default: [])
• quarterly_growth_shipments integer nullable
• quarterly_growth_share number nullable
• monthly_shipments array (default: [])
  • @type string (default: "ImportyetiMonthlyPoint")
  • date string required
  • shipments integer nullable
  • weight integer nullable
  • teu integer nullable
  • china_shipments integer nullable
  • china_weight integer nullable
  • china_teu integer nullable
• shipping_delays array (default: [])
  • @type string (default: "ImportyetiShippingDelay")
  • date string required
  • days integer nullable
• manifest_confidentiality array (default: [])
  • @type string (default: "ImportyetiConfidentialityPeriod")
  • start_date string nullable
  • end_date string nullable
• hs_codes array (default: [])
  • @type string (default: "ImportyetiHsCode")
  • hs_code string required
  • parent_hs_code string nullable
  • description string nullable
  • shipments integer nullable
  • weight integer nullable
  • teu integer nullable
  • url string nullable
• hts_codes array (default: [])
  • @type string (default: "ImportyetiHtsCode")
  • hts_code string required
  • description string nullable
  • shipments integer nullable
  • last_shipment_date string nullable
  • bol_number string nullable
  • product_description string nullable
• product_tags array (default: [])
  • @type string (default: "ImportyetiProductTag")
  • tag string required
  • url string nullable
  • shipments integer nullable
• containers array (default: [])
  • @type string (default: "ImportyetiContainer")
  • container_type string nullable
  • length string nullable
  • group string nullable
  • shipments integer nullable
  • shipments_12m integer nullable
  • shipments_12_24m integer nullable
  • yoy number nullable
  • weight integer nullable
  • teu integer nullable
  • container_count integer nullable
• container_load_types array (default: [])
  • @type string (default: "ImportyetiLoadType")
  • load_type string required
  • shipments integer nullable
  • shipments_share number nullable
• carriers array (default: [])
  • @type string (default: "ImportyetiCarrier")
  • scac_code string required
  • name string nullable
  • url string nullable
  • shipments integer nullable
  • shipments_12m integer nullable
  • shipments_12_24m integer nullable
  • yoy number nullable
  • service_types array (default: [])
    • @type string (default: "ImportyetiServiceType")
    • service_type string required
    • shipments integer nullable
    • shipments_share number nullable
• carriers_per_country array (default: [])
  • @type string (default: "ImportyetiCountryCarriers")
  • country string required
  • carriers array (default: [])
• carrier_diversity number nullable
• carrier_diversity_normalized number nullable
• bill_types array (default: [])
  • @type string (default: "ImportyetiBillType")
  • bill_type string required
  • shipments integer nullable
• origins array (default: [])
  • @type string (default: "ImportyetiOrigin")
  • country string required
  • continent string nullable
  • shipments integer nullable
  • url string nullable
• trade_lanes array (default: [])
  • @type string (default: "ImportyetiTradeLane")
  • origin_port string nullable
  • origin_port_country string nullable
  • origin_port_url string nullable
  • destination_port string nullable
  • destination_port_country string nullable
  • destination_port_region string nullable
  • destination_port_url string nullable
  • destination_port_region_url string nullable
  • shipments integer nullable
  • shipments_12m integer nullable
  • shipments_12_24m integer nullable
  • yoy number nullable
  • weight integer nullable
  • teu integer nullable
  • shipping_cost number nullable
• notify_parties array (default: [])
  • @type string (default: "ImportyetiNotifyParty")
  • name string required
  • url string nullable
  • address string nullable
  • shipments integer nullable
  • shipments_12m integer nullable
  • shipments_12_24m integer nullable
  • yoy number nullable
  • is_internal boolean nullable
  • is_personal_name boolean nullable
• notify_party_shipments integer nullable
• notify_party_shipments_share number nullable
• internal_notify_party_shipments integer nullable
• internal_notify_party_shipments_share number nullable
• has_internal_shipments boolean nullable
• internal_partners_count integer nullable
• companies_at_address_count integer nullable
• other_addresses array (default: [])
  • @type string (default: "ImportyetiOtherAddress")
  • address string required
  • url string nullable
  • shipments integer nullable
  • other_companies_count integer nullable
• contact_addresses array (default: [])
  • @type string (default: "ImportyetiContactAddress")
  • address string nullable
  • last_shipment_date string nullable
  • last_shipment_bol string nullable
• notify_party_addresses array (default: [])
  • @type string (default: "ImportyetiContactAddress")
  • address string nullable
  • last_shipment_date string nullable
  • last_shipment_bol string nullable
• trademarks array (default: [])
  • @type string (default: "ImportyetiTrademarkHolder")
  • name string required
  • trademarks_count integer nullable
• mexico_matches array (default: [])
  • @type string (default: "ImportyetiDatasetMatch")
  • name string required
  • url string nullable
  • shipments integer nullable
• is_uflpa_flagged boolean nullable
• imports_per_country_image string nullable
• top_relationships_image string nullable
• shipments_over_time_image string nullable
• product_breakdown_image string nullable

Errors

• 422 — The request body did not validate Check the fields against this schema. A URN with the wrong prefix is the most common cause.
• 408 — The request ran past its time limit Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.
• 412 — No ImportYeti profile under that id, on either the company or the supplier side Retrying will not help: either the entity does not exist, or the input points at a different one.
• 429 — Too many requests: a rate limit or a usage window is exhausted When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.
• 500 — Something broke on our side Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.
• 529 — Rate limit reached, or the endpoint is overloaded Wait at least 30 seconds, then retry.

Response headers

• X-Error — Error message text (present only on error)
• X-Request-ID — Unique request identifier
• X-Execution-Time — Execution time in seconds
• X-Result-Count — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
• X-Total-Available-Results — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
• X-Warning — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
• X-Retry-After — Seconds to wait before retrying. Present only on 429.