Validation API

Validate product data accuracy with AI-powered quality checks.

Endpoints Overview

Create Validation Job

Start a new validation job to verify product data accuracy.

Endpoint: POST /api/{organization}/product-validation-jobs/create

Request Body

Model Types

Parent Product Validation

Special Behavior for Parent Products:

When validating products marked as parent products (products with variants):

• The system validates parent attributes by comparing them against aggregated data from all child products
• Web search is not used for parent products - validation is based on child product data
• Parent products must have at least one child product with enriched attributes
• The validation checks if parent values correctly represent the product family
• extractImages parameter is ignored for parent products
• Credit consumption is lower for parent products as they don't require web searches
• Confidence scores reflect how well parent attributes match aggregated child data

How Validation Works

1. Fetches fresh product data from external sources
2. Optionally extracts and analyzes product images (if extractImages is enabled)
3. Compares source data and visual information with your existing product attributes
4. AI analyzes each attribute for accuracy using both textual and visual data
5. Returns confidence scores (0-100) and explanations
6. Provides an overall validation score
7. Stores extracted images (if extractImages is enabled)

Example Request

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-validation-jobs/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productIds": ["prod_abc123", "prod_def456"],
    "modelType": "pro-v1",
    "extractImages": false
  }'

Response

{
  "success": true,
  "data": {
    "jobId": "job_val123",
    "status": "pending",
    "totalProducts": 2,
    "modelType": "pro-v1",
    "extractImages": false,
    "createdAt": "2024-01-15T14:00:00Z"
  }
}

List Validation Jobs

Retrieve a paginated list of validation jobs.

Endpoint: POST /api/{organization}/product-validation-jobs/get

Request Body

Example Request

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-validation-jobs/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "limit": 20}'

Response

{
  "success": true,
  "data": {
    "jobs": [
      {
        "id": "job_val123",
        "status": "completed",
        "modelType": "pro-v1",
        "totalProducts": 2,
        "processedCount": 2,
        "successCount": 2,
        "failedCount": 0,
        "createdAt": "2024-01-15T14:00:00Z",
        "completedAt": "2024-01-15T14:05:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 10,
      "totalPages": 1
    }
  }
}

Job Status Values

Get Validation Results

Retrieve detailed validation results for products within a job.

Endpoint: POST /api/{organization}/product-validation-jobs/{job_id}/items/get

Path Parameters

Request Body

Example Request

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-validation-jobs/job_val123/items/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "limit": 20}'

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "item_val111",
        "jobId": "job_val123",
        "productId": "prod_abc123",
        "status": "completed",
        "startedAt": "2024-01-15T14:00:00Z",
        "completedAt": "2024-01-15T14:01:30Z",
        "errorMessage": null,
        "validationResults": {
          "name": {
            "attributeId": "name",
            "attributeName": "Product Name",
            "attributeType": "text",
            "existingValue": "Wireless Headphones",
            "isValid": true,
            "confidence": 95,
            "explanation": "Product name matches source data accurately"
          },
          "brand": {
            "attributeId": "brand",
            "attributeName": "Brand",
            "attributeType": "text",
            "existingValue": "AudioCorp",
            "isValid": false,
            "confidence": 85,
            "explanation": "Source indicates brand should be 'AudioCorp Pro'"
          }
        },
        "overallScore": 78.5
      },
      {
        "id": "item_val222",
        "jobId": "job_val123",
        "productId": "prod_def456",
        "status": "failed",
        "startedAt": "2024-01-15T14:01:30Z",
        "completedAt": "2024-01-15T14:02:00Z",
        "errorMessage": "Unable to fetch source data"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 2,
      "totalPages": 1
    }
  }
}

Validation Result Fields

Item Status Values

Stop Validation Job

Stop a running or pending validation job. Any products already validated will retain their validation results, but remaining products will not be processed.

Endpoint: POST /api/{organization}/product-validation-jobs/{job_id}/stop

Path Parameters

Example Request

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-validation-jobs/job_val123/stop \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "message": "Validation job stopped successfully",
  "data": {
    "jobId": "job_val123",
    "status": "stopped"
  }
}

Error Response

If the job cannot be stopped (already completed, failed, or stopped):

{
  "success": false,
  "message": "Job cannot be stopped because it is not in progress"
}

Notes

• Only jobs with status pending or processing can be stopped
• The currently processing product will complete before the job stops
• A product_validation.stopped webhook event is triggered when a job is stopped
• Pending job items are marked as failed with the message "Job was stopped by user"

Understanding Validation Scores

Confidence Score (0-100)

Indicates how confident the AI is in its validation assessment:

• 90-100: Very high confidence
• 70-89: High confidence
• 50-69: Moderate confidence
• Below 50: Low confidence - manual review recommended

Overall Score (0-100)

Aggregate score for the entire product:

• 80-100: Data quality is good
• 60-79: Some issues need attention
• Below 60: Significant data quality issues

Workflow Example

1. Select Products to Validate

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/products/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "limit": 100}'

2. Start Validation Job

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-validation-jobs/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productIds": ["prod_abc123", "prod_def456"],
    "modelType": "pro-v1",
    "extractImages": false
  }'

3. Check Job Status

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-validation-jobs/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. Review Results

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-validation-jobs/job_val123/items/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

5. Update Invalid Data

For products with invalid data, update using the Products API:

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/products/prod_abc123/update \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "SKU-12345",
    "name": "Wireless Headphones",
    "brand": "AudioCorp Pro"
  }'

Best Practices

1. Regular Validation: Run validation periodically to maintain data quality
2. Focus on Low Scores: Prioritize products with low overall scores
3. Review Explanations: Read AI explanations to understand issues
4. Track Trends: Monitor validation scores over time
5. Use Appropriate Model: Higher-tier models provide more accurate validation
6. Enable Image Extraction: Use extractImages: true when you need to store product images for future reference or visual validation