Search Material Catalog Items
Run bounded text, identifier, and refinement searches against one explicitly selected catalog source.
Choose the result source
The required source parameter selects the catalog to search. source=company searches the represented Company's authorized Material Catalog. source=hph searches the HPH Catalog. There is no automatic mode and no fallback: a search that finds nothing in one source does not continue in the other.
- A request without source, or with any other value, is rejected with 400.
- The response echoes source, and every page of a continued search stays on that source.
- source=hph is available only when the represented Company may currently receive HPH Item Codes; otherwise the request is concealed with 404.
- company_item_id is accepted only with source=company, and hph_item_code only with source=hph.
- Material Catalog Item search accepts direct-Company callers only; partner-application calls are not supported.
Submit a bounded query
The normal search starts with q, for example 1/2 in cxc 90 elbow. At least one criterion is required; the operation is not a browse-all catalog. Send each query parameter at most once; unknown parameters are rejected.
- q is 2 to 256 characters of search text.
- company_item_id is the Company's exact primary identifier, and hph_item_code an exact HPH Item Code.
- identifier_type and identifier_value are sent together. identifier_type is upc (12 digits with a valid check digit), gtin (14 digits with a valid check digit), manufacturer_part_number, or manufacturer_order_number.
- manufacturer (2 to 200 characters) and category (1 to 200 characters) narrow the search and can be combined with other criteria.
- page_size is 10 (the default), 25, or 50. Results are relevance ordered; relevance scores and ranking mechanics are never public.
- Caller-defined sort expressions, arbitrary field names, and internal identifiers are not accepted.
Read counts and continue safely
outcome is results, no_results, or ambiguous_exact_identity. count describes the result universe for the criteria, not only the current page: relation exact or at_least carries a number, and relation unavailable carries null.
- next_cursor is present only when another page exists. Repeat the same criteria and page_size and add that cursor unchanged.
- A cursor is opaque, bound to the same caller, source, and criteria, and expires after about ten minutes.
- An unknown, expired, or mismatched cursor returns 404. 409 MATERIAL_CATALOG_SEARCH_CURSOR_STALE means the catalog changed while paging; restart without a cursor.
- Each page is authenticated, authorized, quota checked, and disclosure reduced again.
Read summaries under current disclosure
Search returns bounded summaries rather than full item details. Company results carry item_type company_item and the item_skey of the Company catalog item; HPH results carry item_type hph_item and the hph_item_code. Each description states its provenance.
- Optional fields with no value are omitted rather than returned as null.
- Manufacturer part number, Manufacturer order number, UPC, and GTIN are omitted when the represented Company's current data restrictions exclude them. An omitted identifier does not deny the result and does not prove that the source lacks a value.
- A search result does not create, approve, or change a mapping.
- Use the company item details or HPH item details operation for complete product information after selecting an item.