Search Endpoint

GET https://api.elexess.com/functions/v1/search

Query Parameters

Authentication

• Recommended: Authorization: el_live_* team API token
• Also supported: user JWT bearer token
• Web clients require a signed-in user session. External integrations should use team API tokens; project anonymous credentials cannot authenticate a search

JSON Response

When stream is not set or false:

{
  "searchterm": "LM358",
  "currency": "EUR",
  "result_count": 42,
  "results": [
    {
      "supplier": "Farnell",
      "supplier_part_number": "1564674",
      "manufacturer": "Texas Instruments",
      "manufacturer_part_number": "LM358P",
      "description": "Op Amp Dual GP ±16V/32V 8-Pin PDIP",
      "stock": 4523,
      "delivery_lead_time_days": 3,
      "factory_lead_time_weeks": null,
      "lead_time": null,
      "prices": [
        { "quantity": 1, "price": 0.452, "currency": "EUR" },
        { "quantity": 10, "price": 0.389, "currency": "EUR" },
        { "quantity": 100, "price": 0.312, "currency": "EUR" }
      ],
      "package": "PDIP-8",
      "country_of_origin": "Malaysia",
      "country_short_code": "MY",
      "tariff_code": "85423390",
      "tariff_code_system": "cn_eu",
      "rohs": true,
      "product_url": "https://...",
      "datasheet_url": "https://...",
      "image_url": "https://..."
    }
  ],
  "supplier_statuses": [
    { "supplier": "Farnell", "status": "success",                  "count": 12, "runtime_ms": 342 },
    { "supplier": "Anglia",  "status": "error_service_unavailable", "count": 0,  "runtime_ms": 20003 },
    { "supplier": "Mouser",  "status": "success_empty_result",      "count": 0,  "runtime_ms": 430 }
  ]
}

Field Notes

• stock is null when availability is unknown; zero means confirmed no stock.
• moq and packing_unit constrain order quantities. Choose only an eligible price break at or below the requested quantity; a larger break does not price a smaller order.
• observed_at is the original observation time, including cache hits. from_cache identifies cache hits; cacheable=false prohibits retaining that offer in browser caches. Missing retention metadata should be treated as permission not established.
• Offers may retain their original currency when no fresh, positive exchange rate is available. Inspect every price currency before comparing values; GBP is supported.
• delivery_lead_time_days is the distributor's shipping or delivery estimate in days, or null when the supplier does not provide one.
• factory_lead_time_weeks is the manufacturer's replenishment lead time in weeks, or null when unavailable. It is not an estimate for an in-stock order.
• lead_time is a deprecated compatibility field. Its legacy supplier mappings may have ambiguous units; do not use it to infer delivery dates. Use the two semantic fields above.
• country_of_origin and country_short_code (ISO 3166-1 alpha-2) are where the part was made, as the supplier reports it, or null. They are not filled in from the supplier's own country.
• tariff_code is the supplier's customs tariff code, or null. Use it only together with tariff_code_system: cn_eu (EU Combined Nomenclature, 8 digits, what an EU export declaration needs), taric (CN plus 2 digits), eu_national (TARIC plus 1 digit), hts_us (US Harmonized Tariff Schedule), hs6 (6-digit Harmonized System) or null when the supplier does not say which schedule the code follows. Every EU system starts with the CN code.
• currency reports the selected response currency. A saved team currency takes precedence over the currency query parameter.
• supplier_statuses[] mirrors the per-supplier outcome of each driver invocation and matches the SSE supplier_result / supplier_empty / supplier_error / supplier_skipped events. Consumers should use this field to distinguish "supplier returned no matches" from "supplier API was unavailable". Values: success, success_empty_result, error_service_unavailable, error_rate_limited, error, skipped_line_card. See the Supplier Status Endpoint for status-page-wide availability.
• skipped_line_card means the supplier was not asked. Some suppliers, such as manufacturer stores, only sell certain manufacturers' parts. They are searched only when the catalog or another supplier's offers show that the part comes from one of those manufacturers. A skipped supplier is neither an error nor "no results", and it never counts toward all_suppliers_failed.

SSE Response

When stream=true, the response uses Server-Sent Events:

Event: search_start

event: search_start
data: {"searchterm":"LM358","currency":"EUR","supplier_count":25}

Event: supplier_result

Sent for each supplier that returns results:

event: supplier_result
data: {"supplier":"Farnell","status":"success","count":5,"runtime_ms":342,"items":[...]}

Event: supplier_empty

Sent when a supplier returns no results:

event: supplier_empty
data: {"supplier":"Buerklin","status":"success_empty_result","runtime_ms":180}

Event: supplier_error

Sent when a supplier fails:

event: supplier_error
data: {"supplier":"Schukat","status":"error_service_unavailable","error":"Supplier request failed","runtime_ms":20004}

Event: supplier_skipped

Sent when a supplier was not asked because it does not sell this part's manufacturer:

event: supplier_skipped
data: {"supplier":"Texas Instruments","status":"skipped_line_card","runtime_ms":0}

A supplier that has not answered after about 23 seconds (33 for Digi-Key) is reported with supplier_error and error_service_unavailable, and the search continues without it.

Keep-alive comments

While suppliers are still running, the stream sends a comment line every 10 seconds:

: keepalive

Server-Sent Events parsers ignore lines that start with :. If you parse the stream yourself, skip them; they carry no data and only keep idle-timeout proxies and clients from closing the connection.

Event: search_complete

Final event with summary:

event: search_complete
data: {"searchterm":"LM358","total_results":42,"all_suppliers_failed":false}

all_suppliers_failed is true only when every queried supplier failed with an availability or rate-limit error. This is the streaming equivalent of the REST path returning 503 (see Error Responses), so a client can distinguish a genuine "no matches" result from a full upstream outage.

Stream End

data: [DONE]

Item Search

With mode=item or mode=auto, the search term can be one of your team's item numbers, or the customer part number of one of your items. The term is matched ignoring case and surrounding spaces. An item number always wins over a customer part number. The item's part numbers are searched in one request:

• Part numbers searched: approved part numbers first, then part numbers in qualification, each in your preference order. Blocked part numbers are never searched, and their offers are left out.
• Credits: one search credit per part number searched, reserved together before any supplier is called. The credits of part numbers that never started are refunded on a best-effort basis: when the search reaches its time limit, the response reports the refunded credits in credits_refunded; when you cancel the request, the refund is attempted too, though no response reports its result.
• Limit: at most 10 part numbers per search. An item with more lists its part numbers without searching; choose up to 10 with link_ids.
• Shared customer part numbers: when several of your items have the searched customer part number, nothing is searched and no credit is used. The response lists up to 20 candidates (id, item_number, description, customer_name, customer_part_number) with not_searched: "several_items" and item: null, plus more_candidates: true when there are more. Search again with the item number you want.
• auto: searches the item when the term is one of your item numbers or customer part numbers, and the part number otherwise. Without mode, a search is always a part number search, as before.
• Preview: preview=true answers JSON, even with stream=true, without searching and without using a credit. For an item it returns the item, its part_numbers, not_searched: "preview", credits_needed and planned_part_numbers, the part numbers a search would cover in order. Shared customer part numbers still return their candidates. In auto mode, a term that is not one of your items returns mode: "part" with credits_needed: 1.

The response adds the item and its part numbers, and every result carries item_match. REST results come as one list sorted by unit price at quantity:

{
  "mode": "item",
  "searchterm": "640609F",
  "currency": "EUR",
  "quantity": 100,
  "item": {
    "id": 7,
    "item_number": "640609F",
    "description": "Power inductor 2.2 µH",
    "customer_name": null,
    "customer_part_number": null
  },
  "part_numbers": [
    {
      "part_number": "74275022",
      "searched": true,
      "links": [{ "id": 11, "manufacturer_part_number": "74275022", "manufacturer": "Würth Elektronik", "approval_status": "approved" }]
    }
  ],
  "supplier_count": 25,
  "credits_reserved": 1,
  "credits_refunded": 0,
  "deadline_reached": false,
  "result_count": 12,
  "results": [
    {
      "supplier": "Mouser",
      "manufacturer": "Würth Elektronik",
      "manufacturer_part_number": "74275022",
      "item_match": { "part_number": "74275022", "link_id": 11, "approval_status": "approved", "flags": [] }
    }
  ],
  "supplier_statuses": [{ "supplier": "Mouser", "part_number": "74275022", "status": "success", "count": 3, "runtime_ms": 412 }]
}

item_match.flags can contain:

When nothing can be searched, the response has not_searched set to no_searchable_part_numbers, too_many_part_numbers (with max_part_numbers) or several_items (with candidates), no results, and no credit is used. With stream=true, search_start carries the item fields above, every supplier event carries part_number, and search_complete adds mode, credits_refunded and deadline_reached.

Error Responses

Related Endpoints

• Watchlist Endpoint
• Parts Endpoint
• Items Endpoint
• Team Part Endpoint
• Manufacturers Endpoint
• Suppliers Endpoint
• Supplier Status Endpoint

When every runnable supplier is temporarily unavailable or throttled, the REST response is HTTP 503 with code: "supplier_unavailable" and Retry-After. SSE reports all_suppliers_failed: true in search_complete. A successful empty search does not set these failure markers. Authentication-service failures retain their separate error response and do not set the supplier-failure code.