Evaluation

Evaluation is an asynchronous compliance review of one promotion version. You trigger it, then receive the result via webhook or by polling. Each evaluation returns per-file results, each with a set of issues and their cited rules.

Trigger evaluation

Evaluation runs asynchronously. The endpoint returns immediately with 202 Accepted.

curl -s -X POST \
  "$API_BASE/v1/promotions/<promotionId>/versions/<versionId>/evaluate" \
  -H "Authorization: Bearer $ADCLEAR_API_KEY" \
  -H "X-External-User-ID: $USER_ID"

const res = await fetch(
  `${API_BASE}/v1/promotions/${promotionId}/versions/${versionId}/evaluate`,
  { method: "POST", headers });
const { evaluationId } = await res.json();

res = requests.post(
    f"{API_BASE}/v1/promotions/{promotion_id}/versions/{version_id}/evaluate",
    headers=headers)
evaluation_id = res.json()["evaluationId"]

Response (202 Accepted):

{ "evaluationId": "eval-uuid-...", "status": "processing", "correlationId": "uuid-..." }

Typical processing time is 30 to 90 seconds, depending on content size and complexity.

Poll evaluation status

Fetch the current status and results for a version. The response includes per-file results, so single-file promotions return an array of one.

GET https://public-api.adclear.ai/v1/promotions/{promotionId}/versions/{versionId}/evaluation

Response (200 OK), succeeded:

{
  "status": "succeeded",
  "results": [
    {
      "evaluationId": "eval-uuid-1",
      "uploadId": "upload-uuid-1",
      "fileName": "brochure.pdf",
      "status": "succeeded",
      "result": {
        "reviewRequired": true,
        "overallAssessment": "Requires review",
        "issues": [
          {
            "recommendation": "Consider adding a risk warning.",
            "rationale": "Financial promotions must include risk warnings per FCA guidelines.",
            "severity": "HIGH",
            "citedRules": [
              { "id": "rule-uuid-...", "name": "Risk Warning Requirement", "product": "Investment", "channel": "Digital" }
            ],
            "location": { "type": "text", "content": "Invest now for guaranteed returns", "pageNumber": 1 }
          }
        ]
      }
    }
  ],
  "correlationId": "uuid-..."
}

While processing, a file’s status is pending and its result is absent. When a file fails, its status is failed and no result is returned. A 404 means no evaluation exists for the version yet; trigger one first. Aggregate status:

Aggregate `status`	Condition
`processing`	Any individual evaluation is still `pending`
`succeeded`	All evaluations have `succeeded`
`failed`	At least one `failed`, none `pending`

Recommended flow

Trigger the evaluation with POST .../evaluate.
Receive the result via a webhook. This is the recommended approach: Adclear pushes the result to your endpoint as soon as it’s ready, with no polling.

Polling is a simpler option for low volume, or a fallback when a webhook is delayed: call GET .../evaluation every 5 to 10 seconds until status is succeeded or failed.

Polling counts against the rate limit of 60 requests per minute per API key, shared across all /v1/* endpoints. Polling one evaluation every 5 seconds uses 12 of those requests a minute; polling several at once will exhaust the budget and return 429, including for your create and evaluate calls. Use webhooks once you evaluate at any volume. See Errors & rate limits.

Polling example

while true; do
  STATUS=$(curl -s "$API_BASE/v1/promotions/$PROMO/versions/$VERSION/evaluation" \
    -H "Authorization: Bearer $ADCLEAR_API_KEY" -H "X-External-User-ID: $USER_ID" | jq -r .status)
  echo "status: $STATUS"
  [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ] && break
  sleep 5
done

async function pollEvaluation(promotionId: string, versionId: string) {
  const url = `${API_BASE}/v1/promotions/${promotionId}/versions/${versionId}/evaluation`;
  for (let i = 0; i < 30; i++) {
    await new Promise((r) => setTimeout(r, 5000));
    const data = await (await fetch(url, { headers })).json();
    if (data.status === "succeeded") {
      for (const r of data.results) console.log(r.fileName, r.result.issues.length, "issue(s)");
      return data;
    }
    if (data.status === "failed") throw new Error("Evaluation failed");
  }
  throw new Error("Polling timed out");
}

import time, requests

def poll_evaluation(promotion_id, version_id):
    url = f"{API_BASE}/v1/promotions/{promotion_id}/versions/{version_id}/evaluation"
    for _ in range(30):  # ~150s at 5s intervals
        time.sleep(5)
        data = requests.get(url, headers=headers).json()
        if data["status"] == "succeeded":
            for r in data["results"]:
                print(r["fileName"], len(r["result"]["issues"]), "issue(s)")
            return data
        if data["status"] == "failed":
            raise RuntimeError("Evaluation failed")
    raise TimeoutError("Polling timed out")

Troubleshooting

Evaluation stuck in processing

Typical evaluation time is 30 to 90 seconds. Continue polling every 5 to 10 seconds for up to 5 minutes. If it’s still processing after that, re-trigger with POST .../evaluate. If it persists, contact support with the correlationId and evaluationId.

Configure a webhook to receive results asynchronously and avoid timeout concerns entirely.

Can I re-evaluate the same version?

Yes. Each POST .../evaluate creates a new evaluation, and GET .../evaluation always returns the most recent result for that version. Previous results are retained internally for audit.

For cross-cutting errors (401, 403, 429, 502), see Errors & rate limits.

Get started

Fundamentals

Adclear API

File API

Trigger evaluation

Poll evaluation status

Recommended flow

Polling example

Troubleshooting

​Trigger evaluation

​Poll evaluation status

​Recommended flow

​Polling example

​Troubleshooting

Trigger evaluation

Poll evaluation status

Recommended flow

Polling example

Troubleshooting