Submit your first item
Understand the approved request shape and the safe recovery path before integrating.
Before you begin
An approved caller will need an authenticated integration, authority to represent the target organization, the item-mapping submit capability, and an approved API origin. These prerequisites are verified by HPH and are not selected in the item JSON body.
- Use synthetic information while evaluating the API in Customer Testing.
- Keep organization, user, application, and credential data out of the item body.
- Create a new idempotency key for each new submission and retain it until the outcome is known.
Submission sequence
Build a JSON item using the submission reference, send it to the approved API origin, and retain the returned operation_reference and correlation_id. The reference page contains the synthetic request and response examples generated from the approved OpenAPI baseline.
- A successful initial response contains no more than five disclosed candidates.
- Use available_actions as server-authored navigation; send a relative href back unchanged to the same API origin.
- Use operation_id to locate the exact API reference. Treat title and description as display text, and honor the structured body, idempotency-key, and confirmation requirements.
- If the outcome is ambiguous, replay the same idempotency key and identical content instead of creating a second business operation.
Continue safely
Every follow-up request is authenticated and authorized again. An operation reference, candidate token, or advertised action never grants authority. Retrieve the current result before acting when your local revisions may be stale.
Read current mapping state and history
The submission result describes one matching workflow. The company-item mapping resources separately report the current production association set and its immutable per-item revision history. Do not treat operation history or candidate results as mapping history.
- Retrieve current metadata first and retain its item_skey, mapping_revision, and complete association_count.
- item_skey is HPH's stable identifier for the owning Company's catalog item.
- Retrieve the complete empty-or-one association result only when metadata advertises an associations link. Its absence means the HPH Item Code is not available under the represented Company's current field policy; do not construct the URL.
- If current-association traversal reports that the mapping revision changed, restart from current metadata.
- History revision 0 is never listed. A positive unmapped revision records a previously mapped item whose current association set became empty.
- History metadata remains available without code disclosure. A history entry advertises its snapshot link only when exact HPH Item Codes may be returned, and historical snapshots intentionally do not attach current descriptions as historical evidence.
Compare permitted and withheld identifier responses
Company field policy controls whether protected association identities are disclosed. The same known item can therefore have the same status, mapping_revision, association_count, and history metadata while presenting different navigation and fields to different represented companies.
- Permitted example: current metadata reports association_count 1 and advertises links.associations; the complete association result contains one hph_item_code and no next page.
- Withheld example: current metadata still reports association_count 1 and item_skey, but omits links.associations entirely; no hph_item_code property is returned.
- Permitted history example: a positive revision with associations advertises its immutable snapshot link.
- Withheld history example: the same revision metadata and complete association_count remain visible, but the snapshot link is omitted.
- An omitted protected field or link is intentional. It is not returned as null, masked text, an empty string, or a placeholder, and consumers must not construct an unadvertised URL.