Getting started - Adclear Manual

Adclear provides an automated compliance evaluation service for promotional content. You upload a file, classify it against your organisation’s regulatory rules, and receive an evaluation. Results, including specific findings with cited rules, are delivered via webhooks. This page covers everything you need before making your first request: the two services, authentication, environments, reference data, error handling, and the questions integrators ask most often.

Your system talks to two services that share a single API key.

Service	Base URL	Responsibilities
File API	`files.adclear.ai`	Resumable chunked file upload; upload status tracking
Integration API	`public-api.adclear.ai`	Promotions, evaluations, reference data, outbound webhooks

Data flow. You initiate an upload via the File API, PUT the file in one or more chunks, then reference the upload by ID when creating a promotion via the Integration API. Evaluation results are delivered asynchronously to your webhook endpoint.

Key concepts

Concept	Description
Promotion	A piece of promotional content submitted for compliance review
Version	An immutable snapshot of uploaded files within a promotion. Version 1 is created with the promotion; subsequent versions represent revisions
Evaluation	An asynchronous compliance review of a specific version. Produces a set of issues with cited rules
Webhook	An outbound HTTP POST from Adclear to your endpoint when an event occurs (for example, when evaluation completes)
Metadata	An arbitrary key-value map you attach at promotion creation. Adclear stores it and echoes it back in every webhook so you can correlate events to your own entities

Supported file formats

Format	MIME type	Max size
PDF	`application/pdf`	30 MB
PNG	`image/png`	30 MB
JPEG	`image/jpeg`	30 MB
WebP	`image/webp`	30 MB
MP4	`video/mp4`	2 GB
MOV	`video/quicktime`	2 GB
MP3	`audio/mpeg`	2 GB
WAV	`audio/wav`	2 GB
DOCX	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	10 MB
XLSX	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`	10 MB
HTML	`text/html`	N/A
Inline text/HTML	N/A	N/A (via `content` field; no upload required)

Files exceeding the size limit are rejected at upload initiation with HTTP 413.

All requests to both services require two headers.

Header	Required	Description
`Authorization`	Yes	`Bearer <your-api-key>`, provided during onboarding
`X-External-User-ID`	Yes	A stable identifier for the acting user in your system (for example, an employee ID)

The API key is scoped to a single Adclear organisation and workspace. Rate limits apply per key (see the Errors tab).

Interactive API documentation

Swagger UI:

File API: https://files.adclear.ai/v1/docs
Integration API: https://public-api.adclear.ai/v1/docs

Machine-readable OpenAPI 3.1 specs:

GET https://files.adclear.ai/v1/openapi.json
GET https://public-api.adclear.ai/v1/openapi.json

Environment	File API	Integration API	Purpose
Staging	`https://files-staging.adclear.ai`	`https://public-api-staging.adclear.ai`	Integration testing with sandbox data
Production	`https://files.adclear.ai`	`https://public-api.adclear.ai`	Live

API keys are environment-specific. A staging key won’t authenticate against production, and vice versa.

Test your integration against staging before switching to production.

Before creating a promotion, fetch the IDs for your organisation’s products, channels, jurisdictions, and target markets.

GET https://public-api.adclear.ai/v1/products
GET https://public-api.adclear.ai/v1/channels
GET https://public-api.adclear.ai/v1/jurisdictions
GET https://public-api.adclear.ai/v1/target-markets

All endpoints return at least { id, name }. Some include additional fields.

Endpoint	Response fields
`/v1/products`	`id`, `name`
`/v1/channels`	`id`, `name`
`/v1/jurisdictions`	`id`, `name`, `countryCode`
`/v1/target-markets`	`id`, `name`, `description`

Results are sorted alphabetically by name. These change infrequently. Cache them and refresh daily.

The classification you provide (products, channels, jurisdiction) determines which regulatory rules are applied during evaluation. Incorrect classification produces irrelevant findings.

All error responses follow a consistent envelope.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      { "type": "field_error", "field": "uploadIds", "message": "Required" }
    ]
  },
  "correlationId": "uuid-for-support"
}

Error codes

Code	HTTP status	Meaning	Action
`VALIDATION_ERROR`	400	Request body failed schema validation	Fix the request payload per the `details` array
`UNAUTHORIZED`	401	Missing or invalid API key	Check the `Authorization` header and key validity
`FORBIDDEN`	403	API key lacks permission for this resource	Contact Adclear to adjust key scoping
`NOT_FOUND`	404	Resource does not exist	Verify the resource ID. It may have been deleted
`CONFLICT`	409	Resource not in expected state (uploads not ready, version not editable)	Retry with back-off
`RATE_LIMITED`	429	Too many requests	Honour the `Retry-After` header
`INTERNAL_ERROR`	500	Unexpected server error	Retry once. If persistent, contact support

Always include the correlationId in support requests. It lets us trace the full request lifecycle.

Rate limits

Service	Scope	Limit
Integration API	All `/v1/*` endpoints	60 requests/minute per API key
File API	`POST /v1/uploads` (initiation only)	30 requests/minute per API key

Chunk uploads (PUT /v1/uploads/{id}) and status checks (GET /v1/uploads/{id}) are not rate-limited.When rate-limited, the response includes a Retry-After header indicating how many seconds to wait before retrying.

Common issues

401 Unauthorized on every request

Verify the Authorization header is Bearer <key> (note the space after Bearer).
Confirm you’re using the correct key for the environment. Staging and production keys are not interchangeable.
Check the key hasn’t been revoked.

403 Forbidden

The API key authenticates but isn’t fully configured for your organisation. Contact Adclear support with the correlationId from the error response.

429 Rate limited

Honour the Retry-After header. If you’re regularly hitting the limit, batch requests or contact support to discuss your usage.

502 from the Integration API

Transient upstream issue. Retry after 2–5 seconds. If the error persists, contact support with the correlationId.

General tips

Use the X-Correlation-ID request header to pass your own trace ID. Adclear echoes it back in every response.
Test against staging before production.
Cache reference data (products, channels, jurisdictions, target markets) and refresh daily.

Do I need webhooks, or can I just poll?

Either works:

Polling: trigger evaluation, then poll GET .../evaluation every 5–10 seconds until status is succeeded or failed.
Webhooks: configure a webhook endpoint during onboarding. Adclear POSTs the result to your endpoint when evaluation completes.

You can use both. Poll as a fallback in case a webhook is delayed.

Can I reuse an upload ID across promotions or versions?

Yes. Upload IDs aren’t consumed. The same upload can be referenced by multiple promotions or versions.

Do uploads expire?

No. Completed uploads are stored indefinitely. If you initiate an upload and never send any chunks, the upload session may eventually become unusable. Complete uploads promptly after initiation.

Can I delete or archive a promotion via the API?

No. The API doesn’t support deleting or archiving promotions. They’re retained for compliance audit purposes.

Which `fileFormat` value should I use?

File type	`fileFormat`
`.pdf`	`pdf`
`.jpg`, `.png`, `.gif`, `.webp`, `.svg`, `.bmp`, `.tiff`	`image`
`.mp4`, `.mov`, `.avi`, `.webm`, `.mkv`, `.wmv`	`video`
`.mp3`, `.wav`, `.aac`, `.ogg`, `.flac`, `.m4a`	`audio`
`.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`, `.txt`, `.csv`, `.rtf`	`document`
Inline text or HTML (no file upload)	`text` (use the `content` field instead of `uploadIds`)

The fileFormat must match the file you uploaded. A .pdf upload uses fileFormat: "pdf", not "document".

How do I generate types from the OpenAPI spec?

Use openapi-typescript:

npx openapi-typescript https://public-api.adclear.ai/v1/openapi.json -o adclear-api.d.ts
npx openapi-typescript https://files.adclear.ai/v1/openapi.json -o adclear-files.d.ts

Or explore the schemas interactively via Swagger UI (Integration API, File API).

Next steps

File upload

Initiate an upload, send chunks, and check status.

Creating promotions

Combine uploads with classification metadata.

Evaluation

Trigger and poll evaluation results.

Webhooks

Receive results asynchronously and verify signatures.

Integration

File API

Integration API

Documentation Index

​Key concepts

​Supported file formats

​Interactive API documentation

​Error codes

​Rate limits

​Common issues

​General tips

​Next steps

File upload

Creating promotions

Evaluation

Webhooks

Key concepts

Supported file formats

Interactive API documentation

Error codes

Rate limits

Common issues

General tips

Next steps