Response shaping

Every endpoint accepts three optional query parameters that change how the response is returned: fields, exclude, and format. Leave them off and you get exactly what the API reference documents.

They change the shape of what comes back, never what the call costs. Data credits are charged per record returned, so trimming fields does not make a call cheaper. See Credits.

fields — keep only what you need

fields takes a comma-separated list of field names. Each record in the response keeps those fields and drops the rest.

curl "https://data.importyeti.com/v1.0/supplier/search?name=yiwu%20yida&page_size=2&fields=title,totalShipments,key" \
  -H "IYApiKey: YOUR_API_KEY"

{
  "requestCost": 0,
  "creditsRemaining": 9997.7,
  "data": [
    {
      "title": "Yiwu Yida Artware",
      "totalShipments": 13,
      "key": "supplier/yiwu-yida-artware"
    },
    {
      "title": "Yiwu Dt Supply Chain Mana",
      "totalShipments": 545914,
      "key": "supplier/yiwu-dt-supply-chain-mana"
    }
  ],
  "executionTime": "15ms"
}

The full record for that route also carries countryCode, type, address, mostRecentShipment, and topCompanies.

exclude — drop what you do not want

exclude is the opposite: name the fields to remove and every other field is kept. This is the better choice when you want most of a record minus one or two heavy fields.

curl "https://data.importyeti.com/v1.0/supplier/search?name=yiwu%20yida&page_size=2&exclude=topCompanies,address,type" \
  -H "IYApiKey: YOUR_API_KEY"

{
  "requestCost": 0,
  "creditsRemaining": 9997.7,
  "data": [
    {
      "title": "Yiwu Yida Artware",
      "countryCode": "CN",
      "totalShipments": 13,
      "mostRecentShipment": "01/04/2023",
      "key": "supplier/yiwu-yida-artware"
    },
    {
      "title": "Yiwu Dt Supply Chain Mana",
      "countryCode": "CN",
      "totalShipments": 545914,
      "mostRecentShipment": "17/12/2024",
      "key": "supplier/yiwu-dt-supply-chain-mana"
    }
  ],
  "executionTime": "15ms"
}

Rules for both

• Use one or the other. Sending fields and exclude together is a 400.
• Field names that a record does not carry are ignored — a typo silently narrows the response rather than failing the call.
• Selection is applied to the top-level fields of each record. Nested objects and arrays are kept or dropped whole; you cannot select contact_info.phone.
• Field order follows the record, not the order you listed.
• The envelope always comes back in full — requestCost, creditsRemaining, executionTime, and the PowerQuery totals. Narrowing the payload never hides what the call cost you.

Where the trimming lands

Records live in different places depending on the endpoint, and the selection follows them. See Core concepts for the full map.

So a trimmed PowerQuery response still pages the same way:

{
  "requestCost": 0.2,
  "creditsRemaining": 500,
  "data": {
    "data": [
      {
        "bol_number": "HLCUGDY251030849",
        "arrival_date": "11/28/2025",
        "company_name": "Ikea Supply Ag"
      },
      {
        "bol_number": "FLXT00003516358A",
        "arrival_date": "11/28/2025",
        "company_name": "Genesco Inc"
      }
    ],
    "totalCount": 59583
  },
  "executionTime": "0ms"
}

format=toon

Add format=toon to get the same data as TOON instead of JSON — a compact text encoding meant for feeding responses to a language model. format=json is the default, and leaving the parameter off changes nothing.

curl "https://data.importyeti.com/v1.0/supplier/search?name=yiwu%20yida&page_size=2&fields=title,totalShipments,key&format=toon" \
  -H "IYApiKey: YOUR_API_KEY"

requestCost: 0
creditsRemaining: 9997.7
data[2]{title,totalShipments,key}:
  Yiwu Yida Artware,13,supplier/yiwu-yida-artware
  Yiwu Dt Supply Chain Mana,545914,supplier/yiwu-dt-supply-chain-mana
executionTime: 15ms

Things to know before you switch a client over:

• A TOON response is served as text/plain; charset=utf-8. Read it as text — response.json() will throw.
• Errors are always JSON, whatever format says. A client that asks for TOON still has to handle a JSON error body.
• Any value other than json or toon is a 400.
• How much it saves depends on the shape of the response. The gain is largest for many records that share the same flat fields — TOON writes the field names once as a header and each record as one line, which is exactly the shape fields produces. A single deeply nested profile saves little.

Rejected requests do not cost credits

A bad fields, exclude, or format value is rejected before the endpoint runs, so a typo never spends data credits. The messages you can get:

{
  "statusCode": 400,
  "message": "fields and exclude cannot be combined; use one or the other",
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": "fields must list at least one field name",
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": "format must be one of: json, toon",
  "error": "Bad Request"
}

See Errors for the rest of the status codes.