List company items using an HPH Item Code

POST/v1/hph/catalog/items/catalog-usage

Request schema: HphItemCatalogUsageRequestV1
Success schema: HphItemCatalogUsageResponseV1
Documented HTTP statuses: 200, 400, 401, 403, 404, 409, 429, 503
Contract: hph-item-catalog-usage-v1.openapi.json

Authorization

Current Enterprise authority and represented-Company access are required for every page. Possession of an item code or cursor grants no authority.

Request guidance

Send one exact HPH Item Code, an optional page_size from 1 through 100 (default 50), and, for a later page, only the cursor returned by the preceding response for the same code.

Request fields

Synthetic request example

{
  "hph_item_code": "012NI0018",
  "page_size": 50
}

Idempotency and recovery

No idempotency key is used because this POST is read-only.

Response guidance

company_item_count is the complete current represented-Company count; company_items contains only the current bounded page. Each row uses the Company's item_skey and nullable Company identifiers. hph_item_code is omitted when restricted without denying the otherwise authorized catalog rows. Send next_cursor back unchanged; it is present only when another page exists. After a stale-cursor conflict, restart from the first page.

Synthetic success example: One page of Company catalog usage

{
  "contract_version": "v1",
  "hph_item_code": "012NI0018",
  "company_item_count": 1,
  "company_items": [
    {
      "item_skey": "11111111-1111-4111-8111-111111111111",
      "company_item_id": "SYNTHETIC-1001",
      "company_item_alt_id": null,
      "description": "Synthetic catalog elbow",
      "lifecycle": "active",
      "mapping_revision": 3,
      "effective_at": "2026-10-27T12:00:00Z"
    }
  ]
}

Additional response examples

HPH Item Code withheld from the response

{
  "contract_version": "v1",
  "company_item_count": 1,
  "company_items": [
    {
      "item_skey": "11111111-1111-4111-8111-111111111111",
      "company_item_id": "SYNTHETIC-1001",
      "company_item_alt_id": null,
      "description": "Synthetic catalog elbow",
      "lifecycle": "active",
      "mapping_revision": 3,
      "effective_at": "2026-10-27T12:00:00Z"
    }
  ]
}