{ "openapi": "3.1.0", "info": { "title": "HPH Integrations HPH item details and catalog usage candidate", "version": "v1", "description": "HPH Integrations public API v1. Available to the Customer Testing group; not available in Production." }, "paths": { "/v1/hph/catalog/items/details": { "post": { "operationId": "GetHphItemDetailsByCodeBatch", "x-runtime-status": "testing-available", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HphItemDetailsByCodeBatchRequestV1" }, "example": { "items": [ { "request_key": "line-1", "hph_item_code": "012NI0018" } ] } } } }, "responses": { "200": { "description": "Ordered HPH item detail results and represented-company usage counts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HphItemDetailsByCodeBatchResponseV1" }, "example": { "contract_version": "v1", "results": [ { "outcome": "available", "request_index": 0, "request_key": "line-1", "item": { "item_ids": { "hph_item_code": "012NI0018", "manufacturer_part_number": "SYN-607", "manufacturer_order_number": "SYN-9055750", "manufacturer_upc": "000000000001" }, "company_item_count": 2, "lifecycle": "active", "availability_status": "A", "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 }, "categorization": { "category": "Synthetic Fittings", "subcategory": "Synthetic Elbows" }, "weight": { "value": 0.177, "unit_of_measure": "LB" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/hph/catalog/items/catalog-usage": { "post": { "operationId": "ListCompanyItemsByHphItemCode", "x-runtime-status": "testing-available", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HphItemCatalogUsageRequestV1" }, "example": { "hph_item_code": "012NI0018", "page_size": 50 } } } }, "responses": { "200": { "description": "One bounded page of represented-company catalog items using the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HphItemCatalogUsageResponseV1" }, "example": { "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" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "components": { "schemas": { "HphItemCodeV1": { "type": "string", "maxLength": 10, "pattern": "^(?:[0-9]{3}[A-Z]{2}|010C |210C |275C1)[0-9]{4}[A-Z]?$" }, "HphItemDetailsByCodeEntryV1": { "type": "object", "additionalProperties": false, "required": ["hph_item_code"], "properties": { "request_key": { "type": "string", "minLength": 1, "maxLength": 64 }, "hph_item_code": { "$ref": "#/components/schemas/HphItemCodeV1" } } }, "HphItemDetailsByCodeBatchRequestV1": { "type": "object", "additionalProperties": false, "required": ["items"], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "items": { "$ref": "#/components/schemas/HphItemDetailsByCodeEntryV1" } } } }, "HphItemIdentifiersV1": { "type": "object", "additionalProperties": false, "properties": { "hph_item_code": { "$ref": "#/components/schemas/HphItemCodeV1" }, "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 } } }, "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 } } }, "HphItemDetailsV1": { "type": "object", "additionalProperties": false, "required": ["item_ids", "company_item_count", "lifecycle", "availability_status", "size", "descriptions", "manufacturer", "categorization", "weight"], "properties": { "item_ids": { "$ref": "#/components/schemas/HphItemIdentifiersV1" }, "company_item_count": { "type": "integer", "minimum": 1 }, "lifecycle": { "type": "string", "minLength": 1, "maxLength": 64 }, "availability_status": { "type": "string", "enum": ["A", "D", "P"] }, "size": { "type": ["string", "null"], "maxLength": 4096 }, "descriptions": { "$ref": "#/components/schemas/ItemDescriptionsV1" }, "manufacturer": { "$ref": "#/components/schemas/ManufacturerV1" }, "categorization": { "oneOf": [{ "$ref": "#/components/schemas/HphCategorizationV1" }, { "type": "null" }] }, "weight": { "oneOf": [{ "$ref": "#/components/schemas/MeasurementV1" }, { "type": "null" }] } } }, "AvailableHphItemDetailsResultV1": { "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/HphItemDetailsV1" } } }, "NotFoundHphItemDetailsResultV1": { "type": "object", "additionalProperties": false, "required": ["outcome", "request_index"], "properties": { "outcome": { "const": "not_found_or_concealed" }, "request_index": { "type": "integer", "minimum": 0, "maximum": 9 }, "request_key": { "type": "string", "maxLength": 64 } } }, "UnavailableHphItemDetailsResultV1": { "type": "object", "additionalProperties": false, "required": ["outcome", "request_index"], "properties": { "outcome": { "const": "temporarily_unavailable" }, "request_index": { "type": "integer", "minimum": 0, "maximum": 9 }, "request_key": { "type": "string", "maxLength": 64 } } }, "HphItemDetailsResultV1": { "oneOf": [ { "$ref": "#/components/schemas/AvailableHphItemDetailsResultV1" }, { "$ref": "#/components/schemas/NotFoundHphItemDetailsResultV1" }, { "$ref": "#/components/schemas/UnavailableHphItemDetailsResultV1" } ] }, "HphItemDetailsByCodeBatchResponseV1": { "type": "object", "additionalProperties": false, "required": ["contract_version", "results"], "properties": { "contract_version": { "const": "v1" }, "results": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/HphItemDetailsResultV1" } } } }, "HphItemCatalogUsageRequestV1": { "type": "object", "additionalProperties": false, "required": ["hph_item_code"], "properties": { "hph_item_code": { "$ref": "#/components/schemas/HphItemCodeV1" }, "page_size": { "type": ["integer", "null"], "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "CompanyItemCatalogUsageEntryV1": { "type": "object", "additionalProperties": false, "required": ["item_skey", "company_item_id", "company_item_alt_id", "description", "lifecycle", "mapping_revision", "effective_at"], "properties": { "item_skey": { "type": "string", "format": "uuid" }, "company_item_id": { "type": ["string", "null"], "maxLength": 255 }, "company_item_alt_id": { "type": ["string", "null"], "maxLength": 255 }, "description": { "type": ["string", "null"], "maxLength": 4096 }, "lifecycle": { "type": "string", "minLength": 1, "maxLength": 64 }, "mapping_revision": { "type": "integer", "minimum": 0 }, "effective_at": { "type": "string", "format": "date-time" } } }, "HphItemCatalogUsageResponseV1": { "type": "object", "additionalProperties": false, "required": ["contract_version", "company_item_count", "company_items"], "properties": { "contract_version": { "const": "v1" }, "hph_item_code": { "$ref": "#/components/schemas/HphItemCodeV1" }, "company_item_count": { "type": "integer", "minimum": 1 }, "company_items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/CompanyItemCatalogUsageEntryV1" } }, "next_cursor": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "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" } } } }, "NotFound": { "description": "Resource not found or concealed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalProblem" } } } }, "Conflict": { "description": "Request or continuation conflict.", "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" } } } } } } }