{ "openapi": "3.1.0", "info": { "title": "HPH Integrations HPH Catalog Item alternatives candidate", "version": "v1", "description": "HPH Integrations public API v1. Available to the Customer Testing group; not available in Production." }, "paths": { "/v1/hph/catalog/items/alternatives": { "post": { "operationId": "GetHphItemAlternatives", "summary": "Get bounded HPH Catalog Item alternatives", "x-runtime-status": "testing-available", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HphItemAlternativesRequestV1" }, "example": { "hph_item_code": "012NI0018", "include": ["manufacturer_list_price"] } } } }, "responses": { "200": { "description": "Closed comparison outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HphItemAlternativesResponseV1" }, "example": { "contract_version": "v1", "outcome": "available", "alternatives": [ { "option_reference": "opaque-short-lived-option-reference", "manufacturer": { "name": "Synthetic Manufacturer" }, "description": "Synthetic alternative description", "size": "1 inch", "manufacturer_part_number": "SYN-100", "availability_status": "A", "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" } } ], "notices": [] } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/NotAuthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/QuotaExceeded" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/catalog/items/alternatives": { "post": { "operationId": "GetHphItemAlternativesByCompanyItem", "summary": "Get bounded HPH Catalog Item alternatives for a represented-company item", "x-runtime-status": "testing-available", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HphItemAlternativesByCompanyItemRequestV1" }, "example": { "company_item_id": "SYNTHETIC-ITEM-100", "alternate_company_item_id": null, "include": ["manufacturer_list_price"] } } } }, "responses": { "200": { "description": "Closed comparison outcome without the privately resolved HPH Item Code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HphItemAlternativesResponseV1" }, "example": { "contract_version": "v1", "outcome": "available", "alternatives": [ { "option_reference": "opaque-short-lived-option-reference", "manufacturer": { "name": "Synthetic Manufacturer" }, "description": "Synthetic alternative description", "size": "1 inch", "manufacturer_part_number": "SYN-100", "availability_status": "A", "manufacturer_list_price": null } ], "notices": [] } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/NotAuthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/QuotaExceeded" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/catalog/items/alternative-selections": { "post": { "operationId": "SelectHphItemAlternative", "summary": "Select one current HPH Catalog Item alternative", "x-runtime-status": "testing-available", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectHphItemAlternativeRequestV1" }, "example": { "option_reference": "opaque-short-lived-option-reference", "company_item_id": "SYNTHETIC-ITEM-100", "alternate_company_item_id": null, "company_description": "Synthetic selected alternative", "reason": "Selected for the represented company catalog.", "confirmed": true } } } }, "responses": { "200": { "description": "The confirmed selection completed or exactly replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectHphItemAlternativeResponseV1" }, "example": { "contract_version": "v1", "operation_reference": "alternative_select_0123456789abcdef0123456789abcdef", "outcome": "selected", "item_skey": "11111111-1111-4111-8111-111111111111", "company_item_id": "SYNTHETIC-ITEM-100", "catalog_revision": 2, "reused": false } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/QuotaExceeded" }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "components": { "schemas": { "HphItemCode": { "type": "string", "minLength": 9, "maxLength": 10, "pattern": "^(?:[0-9]{3}[A-Z]{2}|010C |210C |275C1)[0-9]{4}[A-Z]?$" }, "HphItemAlternativesRequestV1": { "type": "object", "additionalProperties": false, "required": ["hph_item_code"], "properties": { "hph_item_code": { "$ref": "#/components/schemas/HphItemCode" }, "include": { "type": ["array", "null"], "maxItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": ["manufacturer_list_price"] } } } }, "HphItemAlternativesByCompanyItemRequestV1": { "type": "object", "additionalProperties": false, "properties": { "company_item_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 512 }, "alternate_company_item_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 512 }, "include": { "type": ["array", "null"], "maxItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": ["manufacturer_list_price"] } } }, "oneOf": [ { "type": "object", "required": ["company_item_id"], "properties": { "company_item_id": { "type": "string" }, "alternate_company_item_id": { "type": "null" } } }, { "type": "object", "required": ["alternate_company_item_id"], "properties": { "company_item_id": { "type": "null" }, "alternate_company_item_id": { "type": "string" } } } ] }, "SelectHphItemAlternativeRequestV1": { "type": "object", "additionalProperties": false, "required": ["option_reference", "reason", "confirmed"], "properties": { "option_reference": { "type": "string", "minLength": 1, "maxLength": 4096 }, "company_item_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 512 }, "alternate_company_item_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 512 }, "company_description": { "type": ["string", "null"], "minLength": 1, "maxLength": 1024 }, "reason": { "type": "string", "minLength": 1, "maxLength": 512 }, "confirmed": { "type": "boolean", "const": true } } }, "SelectHphItemAlternativeResponseV1": { "type": "object", "additionalProperties": false, "required": ["contract_version", "operation_reference", "outcome", "item_skey", "company_item_id", "catalog_revision", "reused"], "properties": { "contract_version": { "type": "string", "const": "v1" }, "operation_reference": { "type": "string", "minLength": 1 }, "outcome": { "type": "string", "const": "selected" }, "item_skey": { "type": "string", "format": "uuid" }, "company_item_id": { "type": ["string", "null"], "maxLength": 512 }, "catalog_revision": { "type": "integer", "format": "int64", "minimum": 1 }, "reused": { "type": "boolean" } } }, "HphItemAlternativeManufacturerV1": { "type": "object", "additionalProperties": false, "required": ["name"], "properties": { "name": { "type": "string", "minLength": 1 } } }, "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 } } }, "HphItemAlternativeV1": { "type": "object", "additionalProperties": false, "required": ["option_reference", "manufacturer", "description", "size", "availability_status", "manufacturer_list_price"], "properties": { "option_reference": { "type": "string", "minLength": 1, "maxLength": 4096 }, "manufacturer": { "$ref": "#/components/schemas/HphItemAlternativeManufacturerV1" }, "description": { "type": "string", "minLength": 1 }, "size": { "type": ["string", "null"] }, "manufacturer_part_number": { "type": "string", "minLength": 1 }, "availability_status": { "type": "string", "enum": ["A", "P", "D"] }, "manufacturer_list_price": { "oneOf": [ { "$ref": "#/components/schemas/ManufacturerListPriceV1" }, { "type": "null" } ] } } }, "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 } } }, "HphItemAlternativesResponseV1": { "oneOf": [ { "$ref": "#/components/schemas/HphItemAlternativesAvailableResponseV1" }, { "$ref": "#/components/schemas/HphItemAlternativesEmptyResponseV1" } ] }, "HphItemAlternativesAvailableResponseV1": { "type": "object", "additionalProperties": false, "required": ["contract_version", "outcome", "alternatives", "notices"], "properties": { "contract_version": { "type": "string", "const": "v1" }, "outcome": { "type": "string", "const": "available" }, "alternatives": { "type": "array", "minItems": 1, "maxItems": 49, "items": { "$ref": "#/components/schemas/HphItemAlternativeV1" } }, "notices": { "type": "array", "maxItems": 32, "items": { "$ref": "#/components/schemas/ResponseNoticeV1" } } } }, "HphItemAlternativesEmptyResponseV1": { "type": "object", "additionalProperties": false, "required": ["contract_version", "outcome", "alternatives", "notices"], "properties": { "contract_version": { "type": "string", "const": "v1" }, "outcome": { "type": "string", "enum": ["not_cross_referenced", "not_found_or_concealed", "collection_limit_exceeded", "temporarily_unavailable"] }, "alternatives": { "type": "array", "maxItems": 0 }, "notices": { "type": "array", "maxItems": 32, "items": { "$ref": "#/components/schemas/ResponseNoticeV1" } } } }, "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": { "InvalidRequest": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalProblem" } } } }, "Unauthenticated": { "description": "Authentication unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalProblem" } } } }, "NotAuthorized": { "description": "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 identity conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalProblem" } } } }, "UnprocessableEntity": { "description": "The option is stale or cannot be selected", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalProblem" } } } }, "QuotaExceeded": { "description": "Quota exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalProblem" } } } }, "Unavailable": { "description": "Temporarily unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalProblem" } } } } } } }