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 and score asynchronously; clients poll GET until status reaches a terminal state. Both report status with the same uppercase values: PROCESSING while scoring is in flight, then a terminal COMPLETED or ERROR.

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 "COMPLETED", scored_at is populated, and the full payload is available:

{
  "asin": "B07XVTRJKX",
  "region": "us",
  "pdp_id": "9b0a0c4e-3c1d-4b9e-9f08-2c7e3a1f1d77",
  "status": "COMPLETED",
  "name": "Example Product",
  "category": "Fish Oil Supplements",
  "pdp_score": 67,
  "carousel_score": 52.4,
  "hero": {
    "image_id": "...",
    "image_url": "https://...",
    "hero_score": 72.0,
    "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 by your own id 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. You key each PDP on a stable id from your own system (a SKU, PIM id, etc.).

1. Discover a product category

By-id submissions need a product category. Supply a product_category_id (below), an external_category_id, or a gtin/asin/name that Vizit can resolve a category from. To use 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/id/SKU-12345" \
  -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. The id in the path can be any stable identifier from your own system (a SKU, PIM id, etc.), up to 512 characters.

Successful response (202 Accepted):

{
  "id": "SKU-12345",
  "pdp_id": "...",
  "status": "PROCESSING",
  "error_code": null,
  "score_url": "/v1/pdps/id/SKU-12345?retailer=amazon_us"
}

3. Poll for scores

Same polling pattern as the ASIN flow, and the response shape mirrors /v1/pdps/asin/{asin} with id instead of asin and a retailer field instead of region. Pass the optional retailer query parameter (defaulting to amazon_us) to disambiguate the same id submitted under different retailers; the score_url above already carries it.

curl "$BASE_URL/v1/pdps/id/SKU-12345?retailer=amazon_us" \
  -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, 413)

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/id/{id}
  • GET /v1/pdps/id/{id}
• For credentials, token acquisition, and security guidance: Authentication.
• For the cross-cutting error response format: Errors.