Skip to main content
A promotion is a piece of content submitted for compliance review. You create one by combining your uploaded files (or inline text) with classification: the products, channels, and jurisdiction that determine which rules apply.

Create a promotion

Response (201 Created):
Required fields are fileFormat, promotionName, channelIds (at least one), productIds (at least one), and jurisdictionId. publicId is the short, human-readable identifier shown to reviewers (for example 42). Use it when referencing a promotion in support requests or your own UI.

Metadata

The metadata field accepts an arbitrary string-to-string map (up to 20 keys). Use it to pass through your own reference IDs, such as Workfront project and task IDs. Adclear stores it with the promotion and echoes it back in every webhook payload, so you can correlate Adclear events to your system without maintaining a separate mapping. Do not store PII, credentials, or sensitive data.

Text promotions

When fileFormat is "text", provide the content field instead of uploadIds. The content field accepts plain text or HTML.

Handling upload conflicts

If a referenced file hasn’t finished uploading, the request returns 409 Conflict with a details entry of type upload_not_ready. Poll GET /v1/uploads/{uploadId} until each upload’s status is completed, then retry. Use exponential back-off (1s, 2s, 4s, up to ~30s). Small files complete within seconds; files over 100 MB may take longer.

Handling unknown reference IDs

Every channelIds, productIds and jurisdictionId value must be an ID that the reference data endpoints return for your API key’s workspace. If any ID doesn’t exist or belongs to another workspace, the request returns 400 VALIDATION_ERROR and Adclear creates nothing. The details array has one field_error per bad ID, naming the field you sent and the ID:
In a variation set, errors for per-variation fields point at the entry that carried the ID, for example variations.1.channelIds. Fetch the IDs again from the reference data endpoints and retry. A common cause is passing channel IDs as productIds.

Create a variation set

Variations are linked promotions that share a core message but differ by format, channel, or jurisdiction (for example the same ad localised for several markets). Each variation is reviewed independently, and they are grouped so a reviewer sees them together. Create a whole set in one call by sending a variations array instead of a single content set.
curl
Response (201 Created):
Each entry in the response is a full promotion, in the same order you sent it. The shared publicId base with letter suffixes (45-A, 45-B) marks them as one group.

Shared vs per-variation fields

  • Send 2 to 20 variations per request.
  • variations cannot be combined with top-level uploadIds, content, fileFormat, channelIds, or jurisdictionId.
  • One file per variation. For multiple files in a single promotion, use a carousel instead.
  • All or nothing: if any variation fails validation, the whole request is rejected and nothing is created.
Trigger evaluation on each variation’s versionId, the same as a single promotion. To revise one variation after review, create a new version on that variation’s promotionId (see below). The other variations are untouched.

Submit a revision

If a promotion needs changes after review, upload the new file(s) (see File upload), then create a new version on the same promotion. The new version inherits the promotion’s name, channels, products, and jurisdiction. Supply only the new files and any fields you want to override.
The response mirrors create, with an incremented version. Then trigger evaluation on the new version. Each version is evaluated independently, and previous results are retained for audit.

Create-version fields

Inherited vs. overridable. promotionName, channelIds, productIds, and jurisdictionId are set once at promotion creation and can’t change per version. Everything else above can be overridden; omitted fields carry forward from the previous version.

Track the latest version

A promotion can gain new versions outside your integration. A reviewer or teammate can upload a revision in the Adclear app, so the version you created through the API may no longer be the newest. To find the latest version and where it stands in review, call GET /v1/promotions/{promotionId}. It returns 404 if the promotion doesn’t exist, belongs to another workspace, or has been deleted.
curl
Response (200 OK):

Spot a superseded decision

GET /v1/promotions/{promotionId}/versions/{versionId}/decision describes the version you ask about, so a version you already approved keeps returning approved after a newer version appears. The response also tells you whether that version is still the latest:
When you poll a decision, check isLatestVersion before you act on it. If it is false, the decision is for an older version (an approved older version stays approved): follow latestVersionId and read that version’s decision to keep tracking the promotion. latestVersionId always matches the one returned by GET /v1/promotions/{promotionId}.

Frequently asked questions

The fileFormat must match the file you uploaded. A .pdf upload uses fileFormat: "pdf", not "document".
No. The API doesn’t support deleting or archiving promotions. They’re retained for compliance audit purposes.
For cross-cutting errors (401, 403, 429, 502), see Errors & rate limits.