Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.adclear.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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 StatusCondition
processingAny individual evaluation is still pending
succeededAll evaluations have succeeded
failedAt least one failed, none pending
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 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

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

​
Troubleshooting

Symptom: GET .../evaluation keeps returning status: "processing" for longer than expected.Context: Typical evaluation time is 30–90 seconds depending on content size and complexity.Resolution:
  1. Continue polling every 5–10 seconds for up to 5 minutes.
  2. If still processing after 5 minutes, re-trigger the evaluation with POST .../evaluate.
  3. If the issue persists, contact Adclear support with the correlationId and evaluationId.
Configure a webhook to receive results asynchronously instead of polling. This avoids timeout concerns entirely.
Yes. Each call to POST .../evaluate creates a new evaluation. When you poll with GET .../evaluation, you always receive the most recent result for that version. Previous evaluation results are retained internally for audit purposes.
For cross-cutting errors (401, 403, 429, 502), see Getting started → Errors.