Submit an Autodesk Fabrication item for mapping

POST/v1/autodesk-fabrication/item-mapping-requests

Request schema: AutodeskFabricationItemMappingRequestV1
Success schema: AutodeskFabricationItemMappingResponseV1
Documented HTTP statuses: 200, 400, 401, 403, 409, 413, 429, 503
Contract: autodesk-fabrication-item-mapping-v1.openapi.json

Authorization

The service revalidates represented-company authority, entitlement, disclosure, and mapping permission for every request. The represented Company must be allowed to see HPH Item Codes; otherwise the request is refused with 403 MAPPING_OPERATION_NOT_AUTHORIZED.

Request guidance

Send fabrication_item with your item id and description, plus any of group, manufacturer, product, size, material, specification, install_type, source_description, range, finish, upc, oem_code, claimed_hph_item_code, and path. Optional values of '', 'na', 'n/a', '-' or '--' are treated as absent. A claimed_hph_item_code is checked against current evidence, never trusted. Organization, user, and application identity come from the trusted caller boundary, not the body.

Request rules

• Send an Idempotency-Key header. Repeating the same key with the same body returns the stored result (reused: true); the same key with a different body is refused with 409 IDEMPOTENCY_CONFLICT.
• The JSON body is at most 32 KiB and contains exactly the fields listed; unknown fields are refused.
• Optional text fields of '', 'na', 'n/a', '-' or '--' (ignoring case and surrounding spaces) are treated as absent.
• The represented company must be allowed to see HPH Item Codes; otherwise the request is refused with 403 MAPPING_OPERATION_NOT_AUTHORIZED.

Request fields

Synthetic request example

{
  "fabrication_item": {
    "id": "FAB-SYN-100",
    "description": "Synthetic 1/2 in. bronze ball valve",
    "manufacturer": "Synthetic Manufacturing",
    "product": "Valve",
    "size": "1/2 IN",
    "material": "Bronze"
  }
}

Idempotency and recovery

Send a fresh Idempotency-Key for a new submission. Replay the same key with identical content after an ambiguous outcome to receive the stored result with reused set to true; changed content with the same key returns 409 IDEMPOTENCY_CONFLICT, and a submission that is still processing returns a retryable 409 MAPPING_REQUEST_IN_PROGRESS.

Response guidance

company_item.resolution is resolved when the fabrication item matches a company item (company_item_id and mapping_revision are set) or creation_required when the company item must be created first, in which case next_action is company_item_creation_required. status is matched when the item already has an existing_mapping, review_required when candidates need review, or unresolved. Candidates are ranked 1 through 5; review_classification and reasons explain each one. Use operation_reference as the durable public identifier and retain correlation_id for support.

Synthetic success example: Candidates ready for review

{
  "contract_version": "v1",
  "operation_reference": "mapop_0123456789abcdef0123456789abcdef",
  "correlation_id": "corr_synthetic_fab_01",
  "fabrication_item_id": "FAB-SYN-100",
  "company_item": {
    "resolution": "resolved",
    "company_item_id": "ACME-1001",
    "mapping_revision": 3
  },
  "request_revision": 1,
  "result_revision": 1,
  "mapping_revision": 3,
  "status": "review_required",
  "existing_mapping": null,
  "claimed_hph_item_code_status": null,
  "candidates": [
    {
      "candidate_token": "ct_synthetic_0001",
      "rank": 1,
      "hph_item_code": "123AB4567",
      "manufacturer": "Synthetic Manufacturing",
      "description": "Synthetic 1/2 in. bronze ball valve",
      "product": "Valve",
      "material": "Bronze",
      "size": "1/2 IN",
      "item_status": "A",
      "review_classification": "strong",
      "reasons": [
        "description_consistent",
        "size_consistent"
      ],
      "warnings": []
    }
  ],
  "available_actions": [
    "accept_for_review",
    "ignore"
  ],
  "next_action": "accept_for_review",
  "completed_at": "2026-11-11T15:00:00Z",
  "reused": false
}

Additional response examples

Company item must be created first

{
  "contract_version": "v1",
  "operation_reference": "mapop_fedcba9876543210fedcba9876543210",
  "correlation_id": "corr_synthetic_fab_02",
  "fabrication_item_id": "FAB-SYN-200",
  "company_item": {
    "resolution": "creation_required",
    "company_item_id": null,
    "mapping_revision": null
  },
  "request_revision": 1,
  "result_revision": 1,
  "mapping_revision": null,
  "status": "unresolved",
  "existing_mapping": null,
  "claimed_hph_item_code_status": "verified",
  "candidates": [],
  "available_actions": [],
  "next_action": "company_item_creation_required",
  "completed_at": "2026-11-11T15:05:00Z",
  "reused": false
}