Skip to main content
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"
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 statusCondition
processingAny individual evaluation is still pending
succeededAll evaluations have succeeded
failedAt least one failed, none pending
  1. Trigger the evaluation with POST .../evaluate.
  2. 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

​
Troubleshooting

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.
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.