Evaluation

Trigger asynchronous compliance evaluation of a promotion version and poll for results

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",
  "correlationId": "uuid-..."
}

Log the correlationId from every response. Include it in support requests to enable fast tracing of the full request lifecycle.

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

---

Poll Evaluation Status

Check the current status and results of compliance evaluations for a version. The response includes per-file results — single-file promotions return an array of one.

Request:

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

Response (200 OK) — Processing:

{
  "status": "processing",
  "results": [
    {
      "evaluationId": "eval-uuid-1",
      "uploadId": "upload-uuid-1",
      "fileName": "brochure.pdf",
      "status": "succeeded",
      "result": { "reviewRequired": true, "overallAssessment": "...", "issues": [...] }
    },
    {
      "evaluationId": "eval-uuid-2",
      "uploadId": "upload-uuid-2",
      "fileName": "banner.png",
      "status": "pending"
    }
  ]
}

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
            }
          }
        ]
      }
    }
  ]
}

Response (200 OK) — Failed:

{
  "status": "failed",
  "results": [
    {
      "evaluationId": "eval-uuid-1",
      "uploadId": "upload-uuid-1",
      "fileName": "brochure.pdf",
      "status": "failed"
    }
  ]
}

Aggregate status logic:

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

Response (404 Not Found):

Returned when no evaluation exists for the given version. Trigger an evaluation first.

---

Recommended Flow

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 until aggregate status is terminal
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":
        for r in data["results"]:
            issues = r.get("result", {}).get("issues", [])
            print(f"{r.get('fileName', 'unknown')}: {len(issues)} issue(s)")
        break
    elif data["status"] == "failed":
        failed = [r for r in data["results"] if r["status"] == "failed"]
        print(f"Evaluation failed for {len(failed)} file(s)")
        break
    else:
        pending = [r for r in data["results"] if r["status"] == "pending"]
        print(f"Status: {data['status']} ({len(pending)} file(s) pending)...")
else:
    print("Polling timed out")

---

Error Responses

Status	When	Action
404	Promotion or version not found	Verify the promotionId and versionId are correct
404	No evaluation exists (GET only)	Trigger an evaluation first
502	Upstream service error	Retry after a short delay