---
updatedAt: 2026-07-07T09:37:11.000Z
---

# Create persistent categorization

Submits products for categorization and persists the results. Persisted results can be retrieved and modified after the job completes.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Vertex Smart Categorization",
    "description": "Automate and streamline product tax categorization with generative AI and Human-in-the-loop guidance.",
    "version": "1.0.0",
    "termsOfService": "https://www.vertexinc.com/terms-of-use",
    "contact": {
      "name": "Vertex Support",
      "url": "http://www.vertexinc.com/support",
      "email": "support@vertexinc.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.vertexinc.com/terms-of-use"
    }
  },
  "servers": [
    {
      "url": "https://smartcategorization.vertexcloud.com/public-api"
    }
  ],
  "security": [
    {
      "Bearer": []
    }
  ],
  "paths": {
    "/categorize/persist": {
      "post": {
        "operationId": "categorizationPersist",
        "summary": "Create persistent categorization",
        "description": "Submits products for categorization and persists the results. Persisted results can be retrieved and modified after the job completes.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CategorizeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Persistent categorization job created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientJob"
                }
              }
            }
          },
          "400": {
            "description": "Bad request — 'uniqueIdentifierType' is missing; a product is missing 'productUniqueId'; the unique identifier type also appears in 'identifiers'/'concatenatedExtraColumns'; a duplicate 'productUniqueId' value was provided; or 'uniqueIdentifierType' does not match the client's configured unique identifier.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — missing or invalid Bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — caller does not have permission to persist categorization results.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "Bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer Token"
      }
    },
    "schemas": {
      "Product": {
        "type": "object",
        "required": [
          "productUniqueId",
          "productTitle"
        ],
        "properties": {
          "productUniqueId": {
            "type": "string",
            "minLength": 1,
            "description": "The value of the client's configured unique record identifier (e.g. GTIN, SKU, NDC). Required and must be unique across the products in the request. Its type is declared once at the request level via 'uniqueIdentifierType'."
          },
          "productTitle": {
            "type": "string",
            "description": "Title of the product.",
            "minLength": 1,
            "maxLength": 128
          },
          "productDescription": {
            "type": "string",
            "description": "Description of the product."
          },
          "identifiers": {
            "type": "object",
            "description": "Additional product identifiers as key-value pairs. Keys must be one of the accepted identifier types in UPPERCASE canonical form: 'GTIN', 'SKU', 'NDC', 'UDI-DI', 'HIBC', 'MPN', 'Catalog Number', 'UNSPSC', 'HSN'. The type declared in 'uniqueIdentifierType' must NOT appear here — its value belongs in 'productUniqueId'.",
            "propertyNames": {
              "enum": [
                "GTIN",
                "SKU",
                "NDC",
                "UDI-DI",
                "HIBC",
                "MPN",
                "Catalog Number",
                "UNSPSC",
                "HSN"
              ]
            },
            "additionalProperties": {
              "type": "string"
            }
          },
          "concatenatedExtraColumns": {
            "type": "object",
            "description": "Additional attributes provided as key-value pairs.",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "CategorizeRequest": {
        "type": "object",
        "required": [
          "uniqueIdentifierType",
          "products"
        ],
        "properties": {
          "uniqueIdentifierType": {
            "type": "string",
            "description": "The unique record identifier type, in UPPERCASE canonical form. The value carried in each product's 'productUniqueId' is of this type. Must be one of the fixed standard types listed in 'enum' — custom identifier types are NOT accepted via the API (they can only be used through the SmartCat UI). Additionally, if the client already has a configured unique identifier, this value must match it exactly; otherwise the request is rejected with 400.",
            "example": "GTIN",
            "enum": [
              "GTIN",
              "SKU",
              "NDC",
              "UDI-DI",
              "HIBC",
              "MPN",
              "Catalog Number",
              "UNSPSC",
              "HSN"
            ]
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            }
          }
        }
      },
      "ClientJob": {
        "type": "object",
        "required": [
          "id",
          "clientVertexId",
          "startTime",
          "persistent",
          "numProducts",
          "numIssues",
          "retentionDays"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the client job."
          },
          "clientVertexId": {
            "type": "string",
            "format": "uuid",
            "description": "Client id coming from Vertex platform."
          },
          "startTime": {
            "type": "string",
            "format": "date-time",
            "description": "The time when the job started."
          },
          "endTime": {
            "type": "string",
            "format": "date-time",
            "description": "The time when the job completed. Null if still in progress."
          },
          "persistent": {
            "type": "boolean",
            "description": "Indicates whether the job results are persisted and retrievable for modification."
          },
          "numProducts": {
            "type": "integer",
            "description": "The number of products submitted in the job."
          },
          "numIssues": {
            "type": "integer",
            "description": "The number of issues found during the job."
          },
          "blobUri": {
            "type": "string",
            "description": "URI to the blob storage location of the job output."
          },
          "retentionDays": {
            "type": "integer",
            "description": "Number of days the job data is retained before deletion."
          },
          "result": {
            "type": "string",
            "description": "Result summary of the job."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable error message with additional context."
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false
  }
}
```