Ingest a PDP

Vizit exposes two purpose-built PDP ingestion endpoints. Both follow the same shape — PUT /v1/pdps/{identifier_type}/{value} to submit, GET the same path to poll — but they serve different integration patterns. This guide walks each end-to-end and lays out the error catalog and rate-limit posture you should plan around.

Prerequisites

Before any of the requests below will succeed, make sure you have:

• Client credentials provisioned by Vizit for your organization and target environment (production, or dev1–dev5).
• A Bearer token obtained via the OAuth 2.0 client-credentials flow described in Authentication. Cache it until expiry — tokens are valid for 24 hours.
• A request ID strategy. Send X-Request-Id on each request to correlate your logs with Vizit's. If you omit it, Vizit generates one and echoes it on the response.

All examples below assume $BASE_URL is the environment-appropriate hostname (e.g., https://ext.vizit.com) and $TOKEN is your current access token.

Choose the right endpoint

Both flows return 202 Accepted immediately. Scoring runs asynchronously; clients poll GET until status transitions from "processing" to "scored".

Walkthrough: scrape an Amazon ASIN

The scraped-content flow is built for services teams onboarding a customer's ASIN catalog and for partner workflows that want Vizit scores across a target brand's listings without managing images themselves.

1. Submit the ASIN

curl -X PUT "$BASE_URL/v1/pdps/asin/B07XVTRJKX" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"region": "us"}'

Path parameter and body:

Successful response (202 Accepted):

{
  "asin": "B07XVTRJKX",
  "region": "us",
  "pdp_id": "9b0a0c4e-3c1d-4b9e-9f08-2c7e3a1f1d77",
  "status": "processing",
  "score_url": "/v1/pdps/asin/B07XVTRJKX?region=us"
}

score_url is the URL you poll next — it includes the region so you don't have to remember the storefront the PDP was ingested under.

Submitting an ASIN that's already in your library refreshes it (re-scrapes and re-scores) rather than rejecting the request, the same behavior as the in-product refresh button.

2. Poll for scores

curl "$BASE_URL/v1/pdps/asin/B07XVTRJKX?region=us" \
  -H "Authorization: Bearer $TOKEN"

While the pipeline is in flight, the response carries status: "processing" and the score fields are null. Once scoring lands, status flips to "scored", scored_at is populated, and the full payload is available:

{
  "asin": "B07XVTRJKX",
  "region": "us",
  "pdp_id": "9b0a0c4e-3c1d-4b9e-9f08-2c7e3a1f1d77",
  "status": "scored",
  "name": "Example Product",
  "category": "Fish Oil Supplements",
  "pdp_score": 67,
  "carousel_score": 52.4,
  "hero": {
    "image_id": "...",
    "image_url": "https://...",
    "hero_score": 72.0,
    "score_breakdown": { "...": "..." },
    "classification": "Packshot"
  },
  "carousel_images": [
    { "image_id": "...", "position": 1, "vizit_score": 55.0, "classification": "Lifestyle" }
  ],
  "asset_mix": { "total_images": 4, "by_classification": { "Packshot": 1, "Lifestyle": 2, "Feature Highlight": 1 } },
  "scored_at": "2026-05-13T19:42:10Z"
}

End-to-end latency for a typical Amazon ASIN is on the order of tens of seconds, capped by the scrape and scoring pipeline rather than the API layer. A polling interval of 15–30 seconds balances time-to-first-result against request volume.

If the PDP is being refreshed and a prior snapshot exists, the response returns the prior scores alongside status: "processing" so your consumers can keep using the existing data while new scoring runs.

Walkthrough: submit a GTIN with your own images

The caller-supplied-content flow is built for PIM partners pushing their own image sets — Syndigo, Salsify, in-house systems — where Vizit's job is to score the assets you provide, not to scrape a retailer.

1. Discover a product category

GTIN submissions require a product_category_id. Pull the valid IDs once and cache them:

curl "$BASE_URL/v1/product-categories" \
  -H "Authorization: Bearer $TOKEN"

The ASIN flow doesn't need this — categories are inferred server-side from the scrape.

2. Submit the PDP

curl -X PUT "$BASE_URL/v1/pdps/gtin/00012345678905" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hero_image_url": "https://your-cdn.example.com/products/abc/hero.jpg",
    "carousel_image_urls": [
      "https://your-cdn.example.com/products/abc/carousel1.jpg",
      "https://your-cdn.example.com/products/abc/carousel2.jpg"
    ],
    "product_category_id": "5b1a7c30-7e9b-4f23-9b6f-8c12a18d3a40",
    "name": "Example Product",
    "retailer": "amazon_us"
  }'

Vizit downloads the images server-side, stores them, and kicks off the standard scoring pipeline. GTINs accept 8, 12, 13, or 14-digit values.

Successful response (202 Accepted):

{
  "gtin": "00012345678905",
  "pdp_id": "...",
  "status": "processing",
  "score_url": "/v1/pdps/gtin/00012345678905"
}

3. Poll for scores

Same pattern as ASIN. The response shape mirrors /v1/pdps/asin/{asin} with gtin instead of asin and external_id instead of region.

curl "$BASE_URL/v1/pdps/gtin/00012345678905" \
  -H "Authorization: Bearer $TOKEN"

Error cheat sheet

Every non-2xx response follows the standard error shape: error_code, detail, status_code, request_id. Branch on error_code, never on detail.

Validation errors (400)

Resource errors (404)

Auth and rate-limit errors

Upstream errors (5xx)

See Errors for the full shared error format and HTTP status reference.

Rate limits and retries

• Per-organization rate limits are enforced at the API gateway. The exact tier is set when Vizit provisions your credentials; treat a dozen submissions per minute per organization as a safe baseline unless you've been told otherwise.
• Exceeding the limit returns 429 Too Many Requests with a Retry-After header.
• Retry 429 and 5xx responses with exponential backoff (start at ~5s, double on each retry, cap at ~60s).
• Do not retry 4xx responses other than 429 until you've fixed the underlying request — the same input will fail the same way.

What's next

• The full operation contracts are in the API Reference:
  • PUT /v1/pdps/asin/{asin}
  • GET /v1/pdps/asin/{asin}
  • PUT /v1/pdps/gtin/{gtin}
  • GET /v1/pdps/gtin/{gtin}
• For credentials, token acquisition, and security guidance: Authentication.
• For the cross-cutting error response format: Errors.