Data access and disclosure
Understand stable item identities, conditionally available fields, Manufacturer list price, licensed labor, and partial-response notices.
Keep item identities distinct
HPH, company, and Manufacturer identifiers have different owners and disclosure rules. A consumer must not reinterpret one identifier as another or assume that an omitted identifier is unavailable to every company.
- item_skey is HPH's stable SKEY for the owning Company's catalog item and is safe to return to that Company.
- Only identifiers named in the public response contract are supported; do not infer additional identifiers from links or values.
- hph_item_code is HPH proprietary content and appears only when the represented Company's current license and field policy permit it.
- company_item_id and company_item_alt_id remain the Company's own identifiers.
- Manufacturer Part, Manufacturer Order, and Manufacturer UPC identifiers are independently controlled fields.
Treat omission as an intentional boundary
A protected identifier that is withheld by current Company policy is omitted before serialization. It is not returned as null, an empty string, masked text, or an entry in a withheld-fields list. Absence therefore does not prove that the underlying value does not exist.
- Do not require a conditionally disclosed identifier to be present in every successful response.
- Do not construct a follow-up URL that the response did not advertise.
- Use only the identifiers and links documented in the public contract.
- An ordinary authorized field with no current source value is returned as null. That case is distinct from policy-based withholding and from an optional section that was not requested.
HPH Item Code available
The represented Company has the required license and field access, so the association resource contains the HPH Item Code.
{
"contract_version": "hph-integrations-v1",
"item_skey": "11111111-1111-4111-8111-111111111111",
"company_item_id": "SYNTHETIC-ITEM-1001",
"mapping_revision": 3,
"association_count": 1,
"associations": [
{
"hph_item_code": "SYNTHETIC-HPH-001",
"item_status": "active",
"manufacturer_name": "Synthetic Manufacturer",
"description": "Synthetic copper elbow",
"product": "Elbow",
"material": "Copper",
"size": "2 in"
}
],
"links": {
"current": "/v1/catalog/items/mapping?company_item_id=SYNTHETIC-ITEM-1001",
"history": "/v1/catalog/items/mapping/history?company_item_id=SYNTHETIC-ITEM-1001",
"next": null
}
}HPH Item Code withheld
The mapping remains visible as metadata, but the protected association field and its navigation link are omitted.
{
"contract_version": "hph-integrations-v1",
"item_skey": "11111111-1111-4111-8111-111111111111",
"company_item_id": "SYNTHETIC-ITEM-1001",
"mapping": {
"status": "active",
"mapping_revision": 3,
"association_count": 1,
"effective_at": "2026-10-21T12:00:00Z"
},
"links": {
"self": "/v1/catalog/items/mapping?company_item_id=SYNTHETIC-ITEM-1001",
"history": "/v1/catalog/items/mapping/history?company_item_id=SYNTHETIC-ITEM-1001"
}
}Use Manufacturer list price correctly
Manufacturer list price is reference content, not a quote, customer price, transaction price, or promise of availability. When returned, its object keeps price, currency, unit of measure, effective date, and price-sheet identity together.
- A numeric zero is valid only when the authoritative source reports an actual zero price.
- Missing or unavailable price is never fabricated as zero.
- For the current US-only source, an otherwise valid selected price with no source currency uses USD; a present currency is preserved.
- Availability values A, P, and D remain separate from HPH item lifecycle. P means Price-on-Application and may have no numeric list price.
Request licensed labor by provider and method
Labor hours are protected third-party content. MCAA, PHCC, and future providers are authorized independently, while an authorized provider makes all of that provider's supported methods available under the current product direction.
- provider and method are explicit and are never substituted for one another.
- hours, unit_of_measure, effective_date, description, hph_labor_code, and is_default travel as one consistent labor-hour object.
- A valid zero-hour labor unit is returned as zero. Missing, unknown, unauthorized, or unavailable labor is never represented as zero.
- HPH can associate several labor units with one item and provider/method combination; a default request returns only the one authoritative default.
- Integrations applies the represented Company's current labor entitlement before protected labor enters the response, logs, cache, export, webhook, or model context.
Handle partial responses and notices
A valid request does not have to fail in full merely because one optional content section cannot be returned. Bounded notices explain the affected section without disclosing license rows, protected values, hidden item relationships, or internal provider behavior.
- LABOR_NOT_ENTITLED means the requested provider is not available under the represented Company's current license.
- LABOR_DEFAULT_NOT_AVAILABLE means the Company is entitled but no authoritative default exists for the requested provider and method.
- LABOR_TEMPORARILY_UNAVAILABLE identifies a temporary authorized-source failure.
- LABOR_INTEGRITY_UNAVAILABLE means conflicting source evidence prevented safe disclosure.
- MANUFACTURER_LIST_PRICE_NOT_AVAILABLE means the requested current Manufacturer list price could not be returned.
- When every requested labor value is unavailable or unauthorized, labor_hours is omitted and notices explain each requested combination. A mixed response includes the authorized labor_hours and notices for the combinations not returned.
- An optional section that was not requested is omitted without a notice. Missing or unauthorized labor is never returned as null, an empty placeholder, or numeric zero.