Search Material Catalog Items

GET/v1/catalog/items/search

Request schema: None
Success schema: MaterialCatalogSearchResponseV1
Documented HTTP statuses: 200, 400, 401, 403, 404, 409, 429, 503
Contract: material-catalog-search-v1.openapi.json

Authorization

Current Enterprise authority for the represented Company is required, and the request must come from direct-Company caller context; partner-application access is not supported. source=hph additionally requires that the Company may currently receive HPH Item Codes; otherwise the request is concealed with 404.

Request guidance

The request has no body; send each query parameter at most once. source is required and must be company or hph. Supply at least one criterion: q (2 to 256 characters), company_item_id (source=company only), hph_item_code (source=hph only), identifier_type with identifier_value, manufacturer (2 to 200 characters), or category (1 to 200 characters). 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, and must be sent together with identifier_value. page_size is 10 (default), 25, or 50. For the next page, repeat the same criteria and add only the cursor returned by the previous page. Unknown parameters are rejected with 400 INVALID_MATERIAL_CATALOG_SEARCH.

Parameters

Request rules

• Every parameter appears at most once; unknown parameters are rejected.
• At least one of q, company_item_id, hph_item_code, identifier_type/identifier_value, manufacturer or category is required: browsing the whole catalog is not allowed.
• company_item_id requires source=company; hph_item_code requires source=hph.
• identifier_type and identifier_value are sent together or not at all.

Request body

This operation has no JSON request body.

Idempotency and recovery

No idempotency key is used because this operation is read-only. Each request, including each continuation page, is quota checked.

Response guidance

source echoes the searched catalog and there is no fallback between sources. outcome is results, no_results, or ambiguous_exact_identity. count.relation is exact, at_least, or unavailable; value is null only when unavailable. Company items carry item_type company_item and item_skey; HPH items carry item_type hph_item and hph_item_code. Each description states its provenance. Optional fields with no value, and Manufacturer part, order, UPC, and GTIN values withheld by current data restrictions, are omitted. next_cursor is present only when another page exists; it is opaque, bound to the same criteria and caller, and expires after about ten minutes. An unknown or expired cursor returns 404; 409 MATERIAL_CATALOG_SEARCH_CURSOR_STALE means the catalog changed during paging, so restart without a cursor.

Synthetic success example: Company catalog results with another page

{
  "contract_version": "v1",
  "search_reference": "search_SyntheticSearchReference00000001",
  "outcome": "results",
  "source": "company",
  "count": {
    "relation": "at_least",
    "value": 11
  },
  "items": [
    {
      "item_type": "company_item",
      "item_skey": "11111111-1111-4111-8111-111111111111",
      "company_item_id": "SYNTHETIC-1001",
      "descriptions": [
        {
          "value": "Synthetic 1/2 in copper 90 elbow",
          "provenance": "effective_catalog"
        }
      ],
      "manufacturer_name": "Synthetic Manufacturer",
      "manufacturer_part_number": "SYN-607"
    }
  ],
  "next_cursor": "mcs1.synthetic.continuation.0001"
}

Additional response examples

HPH Catalog results with Manufacturer identifiers withheld

{
  "contract_version": "v1",
  "search_reference": "search_SyntheticSearchReference00000002",
  "outcome": "results",
  "source": "hph",
  "count": {
    "relation": "exact",
    "value": 1
  },
  "items": [
    {
      "item_type": "hph_item",
      "hph_item_code": "012NI0018",
      "descriptions": [
        {
          "value": "Synthetic copper elbow",
          "provenance": "hph_authored"
        }
      ],
      "manufacturer_name": "Synthetic Manufacturer"
    }
  ]
}

No results

{
  "contract_version": "v1",
  "search_reference": "search_SyntheticSearchReference00000003",
  "outcome": "no_results",
  "source": "company",
  "count": {
    "relation": "exact",
    "value": 0
  },
  "items": []
}