Get company item details

POST/v1/catalog/items/details

Request schema: CompanyItemDetailsBatchRequestV1
Success schema: CompanyItemDetailsBatchResponseV1
Documented HTTP statuses: 200, 400, 401, 403, 429, 503
Contract: company-item-content-batch-v1.openapi.json

Authorization

Every request requires current Enterprise authority for the represented Company. Each selector is resolved only inside that Company, and current data restrictions are applied before the response is produced.

Request guidance

Send one through ten entries. Each entry must contain exactly one item_skey, company_item_identifier, or hph_item_code selector. The selector type is never inferred from the value. An optional request_key correlates an entry with its result.

Request fields

Synthetic request example

{
  "items": [
    {
      "request_key": "line-1",
      "selector": {
        "company_item_identifier": "SYNTHETIC-1001"
      }
    }
  ]
}

Idempotency and recovery

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

Response guidance

Results preserve request order and use closed per-item outcomes: available, not_found_or_concealed, mapping_required, ambiguous, and temporarily_unavailable. An available result carries details. Ordinary authorized fields with no source value are null. Restricted identifiers are omitted rather than returned as null or masked text.

Synthetic success example: Available item details

{
  "contract_version": "v1",
  "results": [
    {
      "outcome": "available",
      "request_index": 0,
      "request_key": "line-1",
      "details": {
        "item_skey": "b0f01d82-b996-11e0-b635-00137268a1bf",
        "item_ids": {
          "hph_item_code": "012NI0018",
          "company_item_id": "SYNTHETIC-1001",
          "company_item_alt_id": null
        },
        "size": "1 in",
        "descriptions": {
          "company": null,
          "hph_long": "Synthetic copper elbow",
          "hph_short": "Synthetic elbow",
          "manufacturer": null
        },
        "manufacturer": {
          "manufacturer_id": "org-0000-1411",
          "name": "Synthetic Manufacturer",
          "short_name": null
        },
        "availability_status": "A",
        "categorization": {
          "category": "Synthetic Fittings",
          "subcategory": "Synthetic Elbows"
        },
        "weight": {
          "value": 0.177,
          "unit_of_measure": "LB"
        },
        "notices": []
      }
    }
  ]
}

Additional response examples

Closed item-level outcomes

{
  "contract_version": "v1",
  "results": [
    {
      "outcome": "not_found_or_concealed",
      "request_index": 0,
      "request_key": "line-1"
    },
    {
      "outcome": "mapping_required",
      "request_index": 1,
      "request_key": "line-2"
    },
    {
      "outcome": "ambiguous",
      "request_index": 2,
      "request_key": "line-3"
    },
    {
      "outcome": "temporarily_unavailable",
      "request_index": 3,
      "request_key": "line-4"
    }
  ]
}