Create categorization

Learn how to submit products for asynchronous categorization and receive a job ID that you can use to monitor the result.

Endpoint

POST /public-api/categorize

Submits products for categorization and returns a job ID. Results are not persisted and you cannot retrieve or modify them after the job completes.

Authentication

All requests require a valid bearer token in the Authorization header.

Authorization: Bearer {ACCESS_TOKEN}

Request

{
  "uniqueIdentifierType": "GTIN",
  "products": [
    {
      "productUniqueId": "1234567890123",
      "productTitle": "Wireless Mouse",
      "productDescription": "Ergonomic wireless mouse for laptop use.",
      "identifiers": {
        "SKU": "WM-101"
      },
      "concatenatedExtraColumns": {
        "brand": "Vertex Tech"
      }
    }
  ]
}

Property	Type	Required	Description
`uniqueIdentifierType`	string	Yes	The unique record identifier type. Supported values include `GTIN`, `SKU`, `NDC`, `UDI-DI`, `HIBC`, `MPN`, `Catalog Number`, `UNSPSC`, and `HSN`.
`products`	array	Yes	One or more products to categorize.

Example

curl --request POST \
  --url https://smartcategorization.vertexcloud.com/public-api/categorize \
  --header "Authorization: Bearer {ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "uniqueIdentifierType": "GTIN",
    "products": [
      {
        "productUniqueId": "1234567890123",
        "productTitle": "Wireless Mouse",
        "productDescription": "Ergonomic wireless mouse for laptop use.",
        "identifiers": {
          "SKU": "WM-101"
        }
      }
    ]
  }'

Response

{
  "id": "7ecf0bb0-8a90-4fc0-8e51-7c2f1d5a553e",
  "clientVertexId": "4e0864e9-2a1d-4d8f-aeb7-2677f1a19462",
  "startTime": "2026-09-25T12:00:00Z",
  "persistent": false,
  "numProducts": 1,
  "numIssues": 0,
  "retentionDays": 30,
  "result": "Job created"
}

Errors

Status	Description
`400 Bad Request`	The request is invalid. Common reasons include a missing or invalid `uniqueIdentifierType`, duplicate product IDs, or a product missing `productUniqueId`.
`401 Unauthorized`	The bearer token is missing, expired, or invalid.
`500 Internal Server Error`	The service encountered an unexpected error while processing the request.