Skip to main content
This walks the full happy path: authenticate, fetch reference IDs, upload a file, create a promotion, trigger an evaluation, and read the result. Each step links to the page with the full detail.
You need an API key (provided during onboarding) and a file to test with. Run against staging first by swapping the hosts below for their -staging equivalents (see Authentication).
1

Set your credentials

Every request needs your API key and a stable identifier for the acting user in your system.
export ADCLEAR_API_KEY="your-api-key"
export API_BASE="https://public-api.adclear.ai"
export FILES_BASE="https://files.adclear.ai"
export USER_ID="your-internal-user-id"
2

Fetch reference IDs

Classification drives which rules apply. Fetch the IDs for one product, channel, and jurisdiction. See Reference data for all four endpoints.
curl -s "$API_BASE/v1/products" \
  -H "Authorization: Bearer $ADCLEAR_API_KEY" \
  -H "X-External-User-ID: $USER_ID"
# → { "products": [ { "id": "...", "name": "..." } ], "correlationId": "..." }
3

Upload a file

Initiate the upload, then send the file in a single PUT (small files) or several chunks. See File upload for chunking and resume.
# Initiate
curl -s -X POST "$FILES_BASE/v1/uploads" \
  -H "Authorization: Bearer $ADCLEAR_API_KEY" \
  -H "X-External-User-ID: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{ "fileName": "ad.pdf", "fileSize": 2048576, "contentType": "application/pdf" }'
# → { "uploadId": "...", "uploadUrl": "/v1/uploads/...", "maxChunkSize": 52428800 }

# Send the bytes
curl -s -X PUT "$FILES_BASE/v1/uploads/<uploadId>" \
  -H "Authorization: Bearer $ADCLEAR_API_KEY" \
  -H "Content-Type: application/pdf" \
  -H "Content-Range: bytes 0-2048575/2048576" \
  --data-binary @ad.pdf
4

Create a promotion

Combine the upload with your classification. See Creating promotions for every field and for text promotions.
curl -s -X POST "$API_BASE/v1/promotions" \
  -H "Authorization: Bearer $ADCLEAR_API_KEY" \
  -H "X-External-User-ID: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{ "uploadIds": ["<uploadId>"], "fileFormat": "pdf", "promotionName": "Summer Campaign",
        "channelIds": ["<channelId>"], "productIds": ["<productId>"], "jurisdictionId": "<jurisdictionId>" }'
# → 201 { "promotionId": "...", "versionId": "...", "version": 1, "correlationId": "..." }
A 409 means an upload is still processing. Retry with back-off. See Creating promotions.
5

Trigger the evaluation

Evaluation runs asynchronously and 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"
# → 202 { "evaluationId": "...", "status": "processing", "correlationId": "..." }
6

Get the result

Poll until the aggregate status is succeeded or failed. Each result carries the findings for one file. See Evaluation for the full response shape.
curl -s "$API_BASE/v1/promotions/<promotionId>/versions/<versionId>/evaluation" \
  -H "Authorization: Bearer $ADCLEAR_API_KEY" \
  -H "X-External-User-ID: $USER_ID"
# → { "status": "succeeded", "results": [ { "result": { "issues": [ ... ] } } ], "correlationId": "..." }

​
Next steps

Webhooks

Receive results automatically instead of polling, and verify signatures.

Errors & rate limits

Handle the error envelope, status codes, and rate limits.