Submit one item for mapping

POST/v1/item-mapping-requests

Request schema: SingleItemMappingRequestV1
Success schema: SingleItemMappingResponseV1
Documented HTTP statuses: 200, 400, 401, 403, 404, 409, 413, 503
Contract: v1-baseline.json

Authorization

The service revalidates represented-company authority, optional partner delegation, entitlement, disclosure, and submit permission for every request.

Request guidance

The public JSON body contains item information only. Organization, user, application, authorization, and service identity are supplied by the trusted caller boundary and are not item fields.

Request fields

Synthetic request example

{
  "company_item_id": "CUSTOMER-1001",
  "description": "Synthetic copper elbow",
  "mfr_name": "Synthetic Manufacturer",
  "mfr_part": "SYN-90",
  "size": "2 in",
  "weight": 1.25,
  "list_price": 12.34
}

Idempotency and recovery

Send a fresh public idempotency key for a new business operation. Replay the same key and identical content after an ambiguous outcome; changed content with the same key conflicts.

Response guidance

Use operation_reference as the durable public operation identifier. Follow available_actions by sending each relative href back unchanged to the same API origin. Use operation_id to locate the exact reference contract; title and description are display guidance only.

Synthetic success example

{
  "contract_version": "v1",
  "operation_reference": "mapop_0123456789abcdef0123456789abcdef",
  "correlation_id": "example-correlation",
  "company_item_id": "CUSTOMER-1001",
  "result_revision": 1,
  "status": "review_required",
  "reason_codes": [
    "candidate_review_required"
  ],
  "candidates": [
    {
      "candidate_token": "candidate_0123456789abcdef0123456789abcdef",
      "rank": 1,
      "manufacturer": "Synthetic Manufacturer",
      "description": "Synthetic candidate",
      "product": "Synthetic Product",
      "material": "Synthetic Material",
      "size": "2 in",
      "item_status": "active",
      "match_strength": "strong",
      "evidence": [
        {
          "type": "description",
          "outcome": "consistent"
        }
      ],
      "warnings": []
    }
  ],
  "next_action": "review_candidates",
  "available_actions": [
    {
      "action": "get_current_result",
      "title": "Retrieve current mapping result",
      "description": "Retrieves the latest disclosed result and currently available follow-up actions. It does not change the mapping operation.",
      "operation_id": "GetSingleItemMappingCurrentResult",
      "method": "GET",
      "href": "/v1/item-mapping-requests/mapop_0123456789abcdef0123456789abcdef",
      "request_body_required": false,
      "idempotency_key_required": false,
      "confirmation_required": false
    },
    {
      "action": "expand_candidates",
      "title": "Expand mapping candidates",
      "description": "Requests up to ten additional candidates and advances the result revision. It does not approve or activate a mapping.",
      "operation_id": "ExpandSingleItemMappingCandidates",
      "method": "POST",
      "href": "/v1/item-mapping-requests/mapop_0123456789abcdef0123456789abcdef/candidate-expansions",
      "request_body_required": true,
      "idempotency_key_required": true,
      "confirmation_required": true
    }
  ],
  "completed_at": "2026-10-12T12:00:00Z",
  "reused": false
}