> ## Documentation Index
> Fetch the complete documentation index at: https://enrichment-docs.verzla.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submitting Proposals

> Send enriched fields back as pending revisions — with a confidence score per item.

When your model has produced enrichments, submit them as a **batch of proposals**. Each proposal
becomes a **pending revision** on the matched product — it never edits live data. A merchant reviewer
then accepts or rejects it.

The key lever you control here is **confidence**: a 0–100 score per item that tells reviewers how
sure you are. High-confidence proposals can be triaged and accepted fast; low-confidence ones get a
closer look. Sending honest confidence is the single biggest thing you can do to raise your
[acceptance rate](/enrichment/acceptance-rate).

## Endpoint

```http theme={null}
POST /api/enrichment/products/submissions
Content-Type: application/json
```

Requires the `catalog:submit` scope. A submission carries an optional `externalSubmissionId` (your
own idempotency/correlation handle) and a list of items.

```json theme={null}
{
  "externalSubmissionId": "batch-2026-06-22-001",
  "items": [
    {
      "sku": "ABC-123",
      "confidence": 92,
      "name": "Acme 18V Cordless Impact Driver",
      "description": "A compact 18V brushless impact driver delivering 180 Nm of torque...",
      "attributes": [
        {
          "attribute": "Voltage",
          "detail": "18",
          "option": { "optionId": 880, "unit": "V", "priority": 1, "dataType": "NUMBER", "showOnWebsite": true }
        },
        {
          "attribute": "Torque",
          "detail": "180",
          "option": { "optionId": 884, "unit": "Nm", "priority": 2, "dataType": "NUMBER", "showOnWebsite": true }
        }
      ]
    },
    {
      "sku": "XYZ-900",
      "confidence": 47,
      "description": "Provisional description — low signal from source data."
    }
  ]
}
```

```bash theme={null}
curl https://api.verzla.com/api/enrichment/products/submissions \
  -H "X-Api-Client-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d @submission.json
```

## Submission item fields

<ParamField body="sku" type="string" required>
  Identity key used to match the proposal back to a product. Must resolve to exactly one product in
  your organization, or the item comes back `UNMATCHED`.
</ParamField>

<ParamField body="confidence" type="integer">
  Your certainty, **0–100**. Optional but strongly recommended — it drives reviewer triage. Omit it
  (or send `null`) only when you genuinely have no signal.
</ParamField>

<ParamField body="name" type="string">
  Proposed product name. Enrichable.
</ParamField>

<ParamField body="slug" type="string">
  Proposed URL slug. Enrichable.
</ParamField>

<ParamField body="description" type="string">
  Proposed long-form description. Enrichable.
</ParamField>

<ParamField body="attributes" type="array">
  Proposed structured attributes. Align each to a template option via `option.optionId` — see
  [Attribute templates](/enrichment/attribute-templates). Each attribute is
  `{ "attribute": string, "detail": string, "option": { ... } | null }`.
</ParamField>

<ParamField body="files" type="array">
  Proposed document references (array of strings). Enrichable.
</ParamField>

<Info>
  Only the **enrichable** fields above are honored. Include at least one non-empty enrichable field
  per item — an item with nothing to propose is rejected as `REJECTED_FIELDS`.
</Info>

## Confidence: help reviewers triage

Confidence isn't just a number we store — it's how the merchant decides what to review first.

* **80–100** — high confidence. Strong source signal, schema-aligned values. Reviewers can batch
  these and accept quickly.
* **50–79** — moderate. Worth a glance; usually a spot-check.
* **0–49** — low. Flag for careful review; you're proposing despite weak signal.

<Tip>
  Calibrate honestly. Inflating confidence gets low-quality proposals accepted once, then erodes
  reviewer trust and your acceptance rate. Well-calibrated confidence is what lets a merchant clear a
  big batch fast — which is exactly what makes your integration valuable.
</Tip>

## Response

You get one result per submitted item, in order. The `sku` echoes your identity so you can correlate
even when an item is unmatched.

```json theme={null}
[
  {
    "sku": "ABC-123",
    "productId": 90210,
    "revisionId": 55123,
    "status": "CREATED",
    "ignoredFields": []
  },
  {
    "sku": "XYZ-900",
    "productId": 90455,
    "revisionId": 55124,
    "status": "CREATED",
    "ignoredFields": ["gtin"]
  }
]
```

### Result status

<ResponseField name="CREATED" type="status">
  A pending revision was created (`revisionId`) on product `productId`. It's now in the merchant's
  review queue.
</ResponseField>

<ResponseField name="UNMATCHED" type="status">
  No product matched the supplied identity — or the match was ambiguous. Nothing was created. Check
  the SKU.
</ResponseField>

<ResponseField name="REJECTED_FIELDS" type="status">
  The item carried no whitelisted, non-empty enrichable fields, so there was nothing to propose.
</ResponseField>

<ResponseField name="ignoredFields" type="string[]">
  Fields you sent that were dropped because they aren't enrichable or were empty. A useful signal
  that your payload includes data the API won't act on.
</ResponseField>

## Limits & errors

| Condition                      | Response                                                           |
| ------------------------------ | ------------------------------------------------------------------ |
| More than **1000** items       | `400 Bad Request` — "Submission exceeds the maximum of 1000 items" |
| Empty or missing `items`       | `400 Bad Request` — "Submission must contain at least one item"    |
| Missing `catalog:submit` scope | `403 Forbidden`                                                    |

Batch large runs into submissions of up to 1000 items each. Use a distinct `externalSubmissionId`
per batch so you can reconcile results against what you sent.