Skip to main content

​
Trigger Evaluation

Start a compliance evaluation for a specific promotion version. Evaluation runs asynchronously — the endpoint returns immediately with a 202 Accepted status. Request: 
POST https://public-api.adclear.ai/v1/promotions/{promotionId}/versions/{versionId}/evaluate
Response (202 Accepted): 
{
  "evaluationId": "eval-uuid-...",
  "status": "processing"
}
Typical processing time is 30–90 seconds depending on content size and complexity.

​
Poll Evaluation Status

Check the current status and result of the most recent compliance evaluation for a version. Request: 
GET https://public-api.adclear.ai/v1/promotions/{promotionId}/versions/{versionId}/evaluation
Response (200 OK) — Pending: 
{
  "evaluationId": "eval-uuid-...",
  "status": "pending"
}
Response (200 OK) — Succeeded: 
{
  "evaluationId": "eval-uuid-...",
  "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
        }
      }
    ]
  }
}
Response (200 OK) — Failed: 
{
  "evaluationId": "eval-uuid-...",
  "status": "failed"
}
Response (404 Not Found): Returned when no evaluation exists for the given version. Trigger an evaluation first.
  1. Trigger evaluation via POST .../evaluate
  2. Poll via GET .../evaluation every 5–10 seconds until status is succeeded or failed
  3. Alternatively, configure a webhook to receive results asynchronously without polling

​
Polling Example

import time
import requests

API_BASE = "https://public-api.adclear.ai/v1"
HEADERS = {"Authorization": "Bearer <your-api-key>"}

# 1. Trigger
trigger = requests.post(
    f"{API_BASE}/promotions/{promotion_id}/versions/{version_id}/evaluate",
    headers=HEADERS,
)
trigger.raise_for_status()
print(f"Evaluation started: {trigger.json()['evaluationId']}")

# 2. Poll
for _ in range(30):
    time.sleep(5)
    poll = requests.get(
        f"{API_BASE}/promotions/{promotion_id}/versions/{version_id}/evaluation",
        headers=HEADERS,
    )
    poll.raise_for_status()
    data = poll.json()

    if data["status"] == "succeeded":
        print(f"Evaluation complete: {len(data['result']['issues'])} issue(s)")
        break
    elif data["status"] == "failed":
        print("Evaluation failed")
        break
    else:
        print(f"Status: {data['status']}...")
else:
    print("Polling timed out")

​
Error Responses

StatusWhenAction
404Promotion or version not foundVerify the promotionId and versionId are correct
404No evaluation exists (GET only)Trigger an evaluation first
502Upstream service errorRetry after a short delay