Add a company catalog item

POST/v1/catalog/items

Request schema: CreateCompanyCatalogItemRequestV1
Success schema: CreateCompanyCatalogItemResponseV1
Documented HTTP statuses: 200, 201, 400, 401, 403, 409, 429, 503
Contract: company-catalog-item-create-v1.openapi.json

Authorization

The operation requires current direct-Company Enterprise authority, permission to receive the HPH Item Code, and current catalog administration authority; when the request acts for a user, that user must hold catalog mapping administrator access. Partner-application creation is not supported.

Request guidance

Send one exact HPH Item Code. You may also send the Company's primary or alternate item ID, a Company description, and a bounded reason. Do not send an item_skey, Company identity, lifecycle, capacity, license, or role field.

Request fields

Synthetic request example

{
  "hph_item_code": "780TA5241",
  "company_item_id": "COMPANY-1001",
  "alternate_company_item_id": "ALT-1001",
  "company_description": "Synthetic catalog item",
  "reason": "Add the governed item to the company material catalog"
}

Idempotency and recovery

Send exactly one Idempotency-Key header (1 to 128 visible ASCII characters); a missing or invalid key returns 400. Use a new key for a new catalog addition. After an ambiguous result, replay the same key and identical request; an exact completed replay returns the original result without consuming capacity again.

Response guidance

A newly created active item returns 201 with outcome created and the Company item_skey. A 200 reports already_present, inactive_existing (an inactive item that was not reactivated), or an exact replay with reused set to true. A new active item consumes catalog capacity; exact replay and already-present outcomes do not. The response never contains internal HPH item identity.

Synthetic success example: Already present (200)

{
  "contract_version": "v1",
  "operation_reference": "catalogcreate_0123456789abcdef0123456789abcdef",
  "outcome": "already_present",
  "item": {
    "item_skey": "11111111-1111-4111-8111-111111111111",
    "company_item_id": "COMPANY-1001",
    "alternate_company_item_id": "ALT-1001",
    "company_description": "Synthetic catalog item",
    "lifecycle": "active",
    "item_history_revision": 7,
    "observed_at": "2026-11-05T12:00:00Z"
  },
  "reused": true
}

Additional response examples

Created (201)

{
  "contract_version": "v1",
  "operation_reference": "catalogcreate_0123456789abcdef0123456789abcdef",
  "outcome": "created",
  "item": {
    "item_skey": "11111111-1111-4111-8111-111111111111",
    "company_item_id": "COMPANY-1001",
    "alternate_company_item_id": null,
    "company_description": "Synthetic catalog item",
    "lifecycle": "active",
    "item_history_revision": 1,
    "observed_at": "2026-11-05T12:00:00Z"
  },
  "reused": false
}

Inactive item is reported without reactivation

{
  "contract_version": "v1",
  "operation_reference": "catalogcreate_0123456789abcdef0123456789abcdef",
  "outcome": "inactive_existing",
  "item": {
    "item_skey": "11111111-1111-4111-8111-111111111111",
    "company_item_id": "COMPANY-1001",
    "alternate_company_item_id": null,
    "company_description": "Synthetic retired catalog item",
    "lifecycle": "inactive",
    "item_history_revision": 7,
    "observed_at": "2026-11-05T12:00:00Z"
  },
  "reused": false
}