{
  "openapi": "3.1.0",
  "info": {
    "title": "HPH Integrations company item content batch candidate",
    "version": "v1",
    "description": "HPH Integrations public API v1. Available to the Customer Testing group; not available in Production."
  },
  "paths": {
    "/v1/catalog/items/details": {
      "post": {
        "operationId": "GetCompanyItemDetailsBatch",
        "x-runtime-status": "testing-available",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CompanyItemDetailsBatchRequestV1" },
              "example": {
                "items": [
                  {
                    "request_key": "line-1",
                    "selector": { "company_item_identifier": "SYNTHETIC-1001" }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ordered per-item detail results.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CompanyItemDetailsBatchResponseV1" },
                "example": {
                  "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": []
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/catalog/items/price-labor": {
      "post": {
        "operationId": "GetCompanyItemPriceLaborBatch",
        "x-runtime-status": "testing-available",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CompanyItemPriceLaborBatchRequestV1" },
              "example": {
                "items": [
                  {
                    "request_key": "line-1",
                    "selector": { "item_skey": "b0f01d82-b996-11e0-b635-00137268a1bf" }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ordered price and default-labor results.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CompanyItemPriceLaborBatchResponseV1" },
                "example": {
                  "contract_version": "v1",
                  "results": [
                    {
                      "outcome": "available",
                      "request_index": 0,
                      "request_key": "line-1",
                      "item": {
                        "item_skey": "b0f01d82-b996-11e0-b635-00137268a1bf",
                        "manufacturer_list_price": {
                          "price_sheet_skey": "3d4c7bfc-49b0-11e9-9891-00137268a1bf",
                          "price": 18.11,
                          "currency": "USD",
                          "unit_of_measure": "E",
                          "effective_date": "2026-10-01",
                          "price_sheet_number": "SYN-2026-10",
                          "price_sheet_name": "Synthetic price sheet"
                        },
                        "labor_hours": [
                          {
                            "hph_labor_code": "L-SYN-001",
                            "provider": "MCAA",
                            "method": "COMPONENT",
                            "description": "Synthetic component installation",
                            "hours": 0.57,
                            "unit_of_measure": "HOUR",
                            "effective_date": "2026-10-01",
                            "is_default": true
                          }
                        ],
                        "notices": []
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/catalog/items/labor-hours": {
      "post": {
        "operationId": "GetCompanyItemLaborHours",
        "x-runtime-status": "testing-available",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CompanyItemLaborHoursBatchRequestV1" },
              "example": {
                "items": [
                  {
                    "request_key": "line-1",
                    "selector": { "hph_item_code": "012NI0018" }
                  }
                ],
                "labor_hours_filter": {
                  "provider": "MCAA",
                  "method": "COMPONENT",
                  "selection": "item_defaults"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ordered authorized labor-hour results.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CompanyItemLaborHoursBatchResponseV1" },
                "example": {
                  "contract_version": "v1",
                  "results": [
                    {
                      "outcome": "available",
                      "request_index": 0,
                      "request_key": "line-1",
                      "item": {
                        "item_skey": "b0f01d82-b996-11e0-b635-00137268a1bf",
                        "labor_hours": [
                          {
                            "hph_labor_code": "L-SYN-001",
                            "provider": "MCAA",
                            "method": "COMPONENT",
                            "description": "Synthetic component installation",
                            "hours": 0.57,
                            "unit_of_measure": "HOUR",
                            "effective_date": "2026-10-01",
                            "is_default": true
                          }
                        ],
                        "notices": []
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CompanyItemSelectorV1": {
        "oneOf": [
          { "$ref": "#/components/schemas/ItemSkeySelectorV1" },
          { "$ref": "#/components/schemas/CompanyItemIdentifierSelectorV1" },
          { "$ref": "#/components/schemas/HphItemCodeSelectorV1" }
        ]
      },
      "ItemSkeySelectorV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["item_skey"],
        "properties": { "item_skey": { "type": "string", "format": "uuid" } }
      },
      "CompanyItemIdentifierSelectorV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["company_item_identifier"],
        "properties": {
          "company_item_identifier": { "type": "string", "minLength": 1, "maxLength": 255 }
        }
      },
      "HphItemCodeSelectorV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["hph_item_code"],
        "properties": {
          "hph_item_code": { "type": "string", "maxLength": 10, "pattern": "^(?:[0-9]{3}[A-Z]{2}|010C |210C |275C1)[0-9]{4}[A-Z]?$" }
        }
      },
      "CompanyItemBatchEntryV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["selector"],
        "properties": {
          "request_key": { "type": "string", "minLength": 1, "maxLength": 64 },
          "selector": { "$ref": "#/components/schemas/CompanyItemSelectorV1" }
        }
      },
      "CompanyItemDetailsBatchRequestV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["items"],
        "properties": {
          "items": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": { "$ref": "#/components/schemas/CompanyItemBatchEntryV1" }
          }
        }
      },
      "CompanyItemPriceLaborBatchRequestV1": {
        "$ref": "#/components/schemas/CompanyItemDetailsBatchRequestV1"
      },
      "LaborHoursFilterV1": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "provider": { "type": "string", "minLength": 1, "maxLength": 128 },
          "method": { "type": "string", "minLength": 1, "maxLength": 128 },
          "selection": {
            "type": "string",
            "enum": ["all", "item_defaults", "company_default"],
            "default": "all"
          }
        }
      },
      "CompanyItemLaborHoursBatchRequestV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["items"],
        "properties": {
          "items": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": { "$ref": "#/components/schemas/CompanyItemBatchEntryV1" }
          },
          "labor_hours_filter": { "$ref": "#/components/schemas/LaborHoursFilterV1" }
        }
      },
      "CompanyItemDetailsBatchResponseV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["contract_version", "results"],
        "properties": {
          "contract_version": { "const": "v1" },
          "results": {
            "type": "array",
            "maxItems": 10,
            "items": { "$ref": "#/components/schemas/CompanyItemDetailsBatchResultV1" }
          }
        }
      },
      "CompanyItemPriceLaborBatchResponseV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["contract_version", "results"],
        "properties": {
          "contract_version": { "const": "v1" },
          "results": {
            "type": "array",
            "maxItems": 10,
            "items": { "$ref": "#/components/schemas/CompanyItemPriceLaborBatchResultV1" }
          }
        }
      },
      "CompanyItemLaborHoursBatchResponseV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["contract_version", "results"],
        "properties": {
          "contract_version": { "const": "v1" },
          "results": {
            "type": "array",
            "maxItems": 10,
            "items": { "$ref": "#/components/schemas/CompanyItemLaborHoursBatchResultV1" }
          }
        }
      },
      "CompanyItemDetailsBatchResultV1": {
        "oneOf": [
          { "$ref": "#/components/schemas/AvailableDetailsResultV1" },
          { "$ref": "#/components/schemas/UnavailableItemResultV1" }
        ]
      },
      "CompanyItemPriceLaborBatchResultV1": {
        "oneOf": [
          { "$ref": "#/components/schemas/AvailablePriceLaborResultV1" },
          { "$ref": "#/components/schemas/UnavailableItemResultV1" }
        ]
      },
      "CompanyItemLaborHoursBatchResultV1": {
        "oneOf": [
          { "$ref": "#/components/schemas/AvailableLaborHoursResultV1" },
          { "$ref": "#/components/schemas/UnavailableItemResultV1" }
        ]
      },
      "AvailableDetailsResultV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["outcome", "request_index", "details"],
        "properties": {
          "outcome": { "const": "available" },
          "request_index": { "type": "integer", "minimum": 0, "maximum": 9 },
          "request_key": { "type": "string", "maxLength": 64 },
          "details": { "$ref": "#/components/schemas/CompanyItemDetailsResponseV1" }
        }
      },
      "AvailablePriceLaborResultV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["outcome", "request_index", "item"],
        "properties": {
          "outcome": { "const": "available" },
          "request_index": { "type": "integer", "minimum": 0, "maximum": 9 },
          "request_key": { "type": "string", "maxLength": 64 },
          "item": { "$ref": "#/components/schemas/CompanyItemPriceLaborV1" }
        }
      },
      "AvailableLaborHoursResultV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["outcome", "request_index", "item"],
        "properties": {
          "outcome": { "const": "available" },
          "request_index": { "type": "integer", "minimum": 0, "maximum": 9 },
          "request_key": { "type": "string", "maxLength": 64 },
          "item": { "$ref": "#/components/schemas/CompanyItemLaborHoursV1" }
        }
      },
      "UnavailableItemResultV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["outcome", "request_index"],
        "properties": {
          "outcome": {
            "type": "string",
            "enum": ["not_found_or_concealed", "mapping_required", "ambiguous", "temporarily_unavailable"]
          },
          "request_index": { "type": "integer", "minimum": 0, "maximum": 9 },
          "request_key": { "type": "string", "maxLength": 64 }
        }
      },
      "CompanyItemDetailsResponseV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["item_skey", "item_ids", "size", "descriptions", "manufacturer", "availability_status", "categorization", "weight", "notices"],
        "properties": {
          "item_skey": { "type": "string", "format": "uuid" },
          "item_ids": { "$ref": "#/components/schemas/ItemIdentifiersV1" },
          "size": { "type": ["string", "null"], "maxLength": 4096 },
          "descriptions": { "$ref": "#/components/schemas/ItemDescriptionsV1" },
          "manufacturer": { "oneOf": [{ "$ref": "#/components/schemas/ManufacturerV1" }, { "type": "null" }] },
          "availability_status": { "type": "string", "enum": ["A", "D", "P"] },
          "categorization": { "oneOf": [{ "$ref": "#/components/schemas/HphCategorizationV1" }, { "type": "null" }] },
          "manufacturer_list_price": { "$ref": "#/components/schemas/ManufacturerListPriceV1" },
          "labor_hours": { "type": "array", "maxItems": 32, "items": { "$ref": "#/components/schemas/LaborHourV1" } },
          "weight": { "oneOf": [{ "$ref": "#/components/schemas/MeasurementV1" }, { "type": "null" }] },
          "notices": { "type": "array", "maxItems": 32, "items": { "$ref": "#/components/schemas/ResponseNoticeV1" } }
        }
      },
      "CompanyItemPriceLaborV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["item_skey", "notices"],
        "properties": {
          "item_skey": { "type": "string", "format": "uuid" },
          "hph_item_code": {
            "type": "string",
            "maxLength": 10,
            "pattern": "^(?:[0-9]{3}[A-Z]{2}|010C |210C |275C1)[0-9]{4}[A-Z]?$",
            "description": "Included only when the represented company's current data restrictions permit HPH Item Code disclosure."
          },
          "manufacturer_list_price": { "$ref": "#/components/schemas/ManufacturerListPriceV1" },
          "labor_hours": { "type": "array", "maxItems": 1, "items": { "$ref": "#/components/schemas/LaborHourV1" } },
          "notices": { "type": "array", "maxItems": 32, "items": { "$ref": "#/components/schemas/ResponseNoticeV1" } }
        }
      },
      "CompanyItemLaborHoursV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["item_skey", "notices"],
        "properties": {
          "item_skey": { "type": "string", "format": "uuid" },
          "hph_item_code": {
            "type": "string",
            "maxLength": 10,
            "pattern": "^(?:[0-9]{3}[A-Z]{2}|010C |210C |275C1)[0-9]{4}[A-Z]?$",
            "description": "Included only when the represented company's current data restrictions permit HPH Item Code disclosure."
          },
          "labor_hours": { "type": "array", "maxItems": 256, "items": { "$ref": "#/components/schemas/LaborHourV1" } },
          "notices": { "type": "array", "maxItems": 32, "items": { "$ref": "#/components/schemas/ResponseNoticeV1" } }
        }
      },
      "ItemIdentifiersV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["company_item_id", "company_item_alt_id"],
        "properties": {
          "hph_item_code": { "type": "string", "maxLength": 10, "pattern": "^(?:[0-9]{3}[A-Z]{2}|010C |210C |275C1)[0-9]{4}[A-Z]?$" },
          "company_item_id": { "type": ["string", "null"], "maxLength": 255 },
          "company_item_alt_id": { "type": ["string", "null"], "maxLength": 255 },
          "manufacturer_part_number": { "type": "string", "maxLength": 255 },
          "manufacturer_order_number": { "type": "string", "maxLength": 255 },
          "manufacturer_upc": { "type": "string", "maxLength": 255 }
        }
      },
      "ItemDescriptionsV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["company", "hph_long", "hph_short", "manufacturer"],
        "properties": {
          "company": { "type": ["string", "null"], "maxLength": 4096 },
          "hph_long": { "type": ["string", "null"], "maxLength": 4096 },
          "hph_short": { "type": ["string", "null"], "maxLength": 4096 },
          "manufacturer": { "type": ["string", "null"], "maxLength": 4096 }
        }
      },
      "ManufacturerV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["manufacturer_id", "name", "short_name"],
        "properties": {
          "manufacturer_id": { "type": "string", "minLength": 1, "maxLength": 255 },
          "name": { "type": ["string", "null"], "maxLength": 4096 },
          "short_name": { "type": ["string", "null"], "maxLength": 4096 }
        }
      },
      "HphCategorizationV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["category", "subcategory"],
        "properties": {
          "category": { "type": ["string", "null"], "maxLength": 4096 },
          "subcategory": { "type": ["string", "null"], "maxLength": 4096 }
        }
      },
      "ManufacturerListPriceV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["price_sheet_skey", "price", "currency", "unit_of_measure", "effective_date", "price_sheet_number", "price_sheet_name"],
        "properties": {
          "price_sheet_skey": { "type": "string", "format": "uuid" },
          "price": { "type": "number", "minimum": 0 },
          "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
          "unit_of_measure": { "type": "string", "minLength": 1, "maxLength": 128 },
          "effective_date": { "type": "string", "format": "date" },
          "price_sheet_number": { "type": "string", "minLength": 1, "maxLength": 255 },
          "price_sheet_name": { "type": ["string", "null"], "maxLength": 4096 }
        }
      },
      "LaborHourV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["hph_labor_code", "provider", "method", "description", "hours", "unit_of_measure", "effective_date", "is_default"],
        "properties": {
          "hph_labor_code": { "type": "string", "minLength": 1, "maxLength": 128 },
          "provider": { "type": "string", "minLength": 1, "maxLength": 128 },
          "method": { "type": "string", "minLength": 1, "maxLength": 128 },
          "description": { "type": "string", "minLength": 1, "maxLength": 4096 },
          "hours": { "type": "number", "minimum": 0 },
          "unit_of_measure": { "type": "string", "minLength": 1, "maxLength": 128 },
          "effective_date": { "type": "string", "format": "date" },
          "is_default": { "type": "boolean" }
        }
      },
      "MeasurementV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["value", "unit_of_measure"],
        "properties": {
          "value": { "type": "number", "minimum": 0 },
          "unit_of_measure": { "type": "string", "minLength": 1, "maxLength": 128 }
        }
      },
      "ResponseNoticeV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["code", "title", "description", "target", "provider", "method"],
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "LABOR_DEFAULT_NOT_CONFIGURED",
              "LABOR_PREFERENCE_TEMPORARILY_UNAVAILABLE",
              "LABOR_NOT_ENTITLED",
              "LABOR_DEFAULT_NOT_AVAILABLE",
              "LABOR_TEMPORARILY_UNAVAILABLE",
              "LABOR_INTEGRITY_UNAVAILABLE",
              "LABOR_NOT_AVAILABLE",
              "MANUFACTURER_LIST_PRICE_NOT_AVAILABLE"
            ]
          },
          "title": { "type": "string", "minLength": 1, "maxLength": 255 },
          "description": { "type": "string", "minLength": 1, "maxLength": 4096 },
          "target": { "type": "string", "enum": ["labor_hours", "manufacturer_list_price"] },
          "provider": { "type": ["string", "null"], "maxLength": 128 },
          "method": { "type": ["string", "null"], "maxLength": 128 }
        }
      },
      "ExternalProblem": { "type": "object", "additionalProperties": false, "required": ["type", "title", "status", "code", "correlation_id", "retryable", "errors"], "description": "Problem details as sent on the wire (application/problem+json). Field names are snake_case, like every other request and response body.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "correlation_id": { "type": "string" }, "retryable": { "type": "boolean" }, "errors": { "type": ["object", "null"], "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }
    },
    "responses": {
      "BadRequest": { "description": "Invalid request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalProblem" } } } },
      "Unauthorized": { "description": "Authentication unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalProblem" } } } },
      "Forbidden": { "description": "Operation not authorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalProblem" } } } },
      "TooManyRequests": { "description": "Quota unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalProblem" } } } },
      "Unavailable": { "description": "Dependency unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalProblem" } } } }
    }
  }
}