{
  "openapi": "3.1.0",
  "info": {
    "title": "HPH Integrations Autodesk Fabrication item mapping",
    "version": "v1",
    "description": "HPH Integrations public API v1. Available to the Customer Testing group; not available in Production."
  },
  "paths": {
    "/v1/autodesk-fabrication/item-mapping-requests": {
      "post": {
        "operationId": "SubmitAutodeskFabricationItemMapping",
        "x-runtime-status": "testing-available",
        "x-idempotency-key-required": true,
        "x-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."
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AutodeskFabricationItemMappingRequestV1"
              },
              "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"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One bounded mapping result for the fabrication item.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutodeskFabricationItemMappingResponseV1"
                },
                "example": {
                  "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
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/QuotaExceeded"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AutodeskFabricationItemMappingRequestV1": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "fabrication_item"
        ],
        "properties": {
          "fabrication_item": {
            "$ref": "#/components/schemas/AutodeskFabricationItemV1"
          }
        }
      },
      "AutodeskFabricationItemV1": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "description"
        ],
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 255,
            "minLength": 1,
            "description": "Your Autodesk Fabrication item identifier. Letters, digits and identifier punctuation only."
          },
          "description": {
            "type": "string",
            "maxLength": 4096,
            "minLength": 1,
            "description": "The item description used for matching."
          },
          "group": {
            "type": "string",
            "maxLength": 512
          },
          "manufacturer": {
            "type": "string",
            "maxLength": 512
          },
          "product": {
            "type": "string",
            "maxLength": 512
          },
          "size": {
            "type": "string",
            "maxLength": 512
          },
          "material": {
            "type": "string",
            "maxLength": 512
          },
          "specification": {
            "type": "string",
            "maxLength": 512
          },
          "install_type": {
            "type": "string",
            "maxLength": 512
          },
          "source_description": {
            "type": "string",
            "maxLength": 4096
          },
          "range": {
            "type": "string",
            "maxLength": 512
          },
          "finish": {
            "type": "string",
            "maxLength": 512
          },
          "upc": {
            "type": "string",
            "maxLength": 255
          },
          "oem_code": {
            "type": "string",
            "maxLength": 255
          },
          "claimed_hph_item_code": {
            "type": "string",
            "maxLength": 128,
            "description": "An HPH Item Code your system already associates with the item. It is checked, never trusted; see claimed_hph_item_code_status."
          },
          "path": {
            "type": "string",
            "maxLength": 2048
          }
        }
      },
      "AutodeskFabricationItemMappingResponseV1": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contract_version",
          "operation_reference",
          "correlation_id",
          "fabrication_item_id",
          "company_item",
          "request_revision",
          "result_revision",
          "mapping_revision",
          "status",
          "existing_mapping",
          "claimed_hph_item_code_status",
          "candidates",
          "available_actions",
          "next_action",
          "completed_at",
          "reused"
        ],
        "properties": {
          "contract_version": {
            "type": "string",
            "const": "v1"
          },
          "operation_reference": {
            "type": "string",
            "minLength": 1
          },
          "correlation_id": {
            "type": "string",
            "minLength": 1
          },
          "fabrication_item_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          "company_item": {
            "$ref": "#/components/schemas/AutodeskFabricationCompanyItemV1"
          },
          "request_revision": {
            "type": "integer",
            "minimum": 1
          },
          "result_revision": {
            "type": "integer",
            "minimum": 1,
            "description": "Always equal to request_revision."
          },
          "mapping_revision": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "description": "The company item's mapping revision; null when the company item must first be created."
          },
          "status": {
            "type": "string",
            "enum": [
              "matched",
              "review_required",
              "unresolved"
            ]
          },
          "existing_mapping": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/AutodeskFabricationExistingMappingV1"
              },
              {
                "type": "null"
              }
            ]
          },
          "claimed_hph_item_code_status": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "verified",
              "invalid_format",
              "not_found",
              "inactive",
              "conflicting_with_current_evidence",
              "reference_data_unavailable",
              null
            ],
            "description": "Null when no claimed_hph_item_code was sent."
          },
          "candidates": {
            "type": "array",
            "maxItems": 5,
            "items": {
              "$ref": "#/components/schemas/AutodeskFabricationCandidateV1"
            }
          },
          "available_actions": {
            "type": "array",
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "accept_for_review",
                "ignore"
              ]
            }
          },
          "next_action": {
            "type": "string",
            "enum": [
              "accept_for_review",
              "company_item_creation_required",
              "none"
            ]
          },
          "completed_at": {
            "type": "string",
            "format": "date-time"
          },
          "reused": {
            "type": "boolean",
            "description": "True when this is the stored result of an earlier request with the same Idempotency-Key."
          }
        }
      },
      "AutodeskFabricationCompanyItemV1": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "resolution",
          "company_item_id",
          "mapping_revision"
        ],
        "properties": {
          "resolution": {
            "type": "string",
            "enum": [
              "resolved",
              "creation_required"
            ]
          },
          "company_item_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Set when resolution is resolved; null when creation_required."
          },
          "mapping_revision": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0
          }
        }
      },
      "AutodeskFabricationExistingMappingV1": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "hph_item_code",
          "mapping_revision"
        ],
        "properties": {
          "hph_item_code": {
            "type": "string",
            "minLength": 1
          },
          "mapping_revision": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "AutodeskFabricationCandidateV1": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "candidate_token",
          "rank",
          "hph_item_code",
          "manufacturer",
          "description",
          "product",
          "material",
          "size",
          "item_status",
          "review_classification",
          "reasons",
          "warnings"
        ],
        "properties": {
          "candidate_token": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "rank": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5
          },
          "hph_item_code": {
            "type": "string",
            "minLength": 1
          },
          "manufacturer": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "product": {
            "type": [
              "string",
              "null"
            ]
          },
          "material": {
            "type": [
              "string",
              "null"
            ]
          },
          "size": {
            "type": [
              "string",
              "null"
            ]
          },
          "item_status": {
            "type": "string",
            "minLength": 1
          },
          "review_classification": {
            "type": "string",
            "enum": [
              "strong",
              "possible",
              "limited",
              "conflicting"
            ]
          },
          "reasons": {
            "type": "array",
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "claimed_hph_item_code_consistent",
                "manufacturer_consistent",
                "manufacturer_identifier_consistent",
                "description_consistent",
                "product_consistent",
                "material_consistent",
                "size_consistent",
                "submitted_evidence_conflict",
                "limited_matching_evidence"
              ]
            }
          },
          "warnings": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 256
            }
          }
        }
      },
      "ExternalProblem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "title",
          "status",
          "code",
          "correlation_id",
          "retryable",
          "errors"
        ],
        "description": "Problem details as sent on the wire (application/problem+json). Field names are snake_case, like every other request and response body.",
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "code": {
            "type": "string"
          },
          "correlation_id": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request; errors lists each invalid field.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ExternalProblem"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Authentication failed.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ExternalProblem"
            }
          }
        }
      },
      "Forbidden": {
        "description": "MAPPING_OPERATION_NOT_AUTHORIZED: the caller is not authorized to map items for the represented company, including when the represented company is not allowed to see HPH Item Codes.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ExternalProblem"
            }
          }
        }
      },
      "Conflict": {
        "description": "IDEMPOTENCY_CONFLICT (the key is bound to a different request) or MAPPING_REQUEST_IN_PROGRESS (retryable: the same request is still processing).",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ExternalProblem"
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "PAYLOAD_TOO_LARGE: the body exceeds 32 KiB.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ExternalProblem"
            }
          }
        }
      },
      "QuotaExceeded": {
        "description": "QUOTA_EXCEEDED: the submission quota is unavailable.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ExternalProblem"
            }
          }
        }
      },
      "Unavailable": {
        "description": "Temporarily unavailable; the problem says whether a retry may succeed.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ExternalProblem"
            }
          }
        }
      }
    }
  }
}