Creating promotions

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

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": ["a1b2c3d4-..."],
    "fileFormat": "pdf",
    "promotionName": "Summer Campaign 2026",
    "channelIds": ["<channel-id>"],
    "productIds": ["<product-id>"],
    "jurisdictionId": "<jurisdiction-id>",
    "metadata": { "workfrontProjectId": "PROJ-123", "workfrontTaskId": "TASK-456" }
  }'

const res = await fetch(`${API_BASE}/v1/promotions`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    uploadIds: ["a1b2c3d4-..."],
    fileFormat: "pdf",
    promotionName: "Summer Campaign 2026",
    channelIds: ["<channel-id>"],
    productIds: ["<product-id>"],
    jurisdictionId: "<jurisdiction-id>",
    metadata: { workfrontProjectId: "PROJ-123", workfrontTaskId: "TASK-456" },
  }),
});
const { promotionId, versionId } = await res.json();

res = requests.post(f"{API_BASE}/v1/promotions", headers=headers, json={
    "uploadIds": ["a1b2c3d4-..."],
    "fileFormat": "pdf",
    "promotionName": "Summer Campaign 2026",
    "channelIds": ["<channel-id>"],
    "productIds": ["<product-id>"],
    "jurisdictionId": "<jurisdiction-id>",
    "metadata": {"workfrontProjectId": "PROJ-123", "workfrontTaskId": "TASK-456"},
})
promotion_id, version_id = res.json()["promotionId"], res.json()["versionId"]

Response (201 Created):

{
  "promotionId": "promo-uuid-...",
  "versionId": "version-uuid-...",
  "version": 1,
  "publicId": "42",
  "metadata": { "workfrontProjectId": "PROJ-123", "workfrontTaskId": "TASK-456" },
  "correlationId": "corr-uuid-..."
}

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.

{
  "content": "<p>Summer savings: earn up to 5% AER on our fixed-rate ISA.</p>",
  "fileFormat": "text",
  "promotionName": "ISA Summer Campaign 2026",
  "channelIds": ["<channel-id>"],
  "productIds": ["<product-id>"],
  "jurisdictionId": "<jurisdiction-id>"
}

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.

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 -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 '{
    "promotionName": "Spring Campaign 2026",
    "productIds": ["<product-id>"],
    "deadline": "2026-09-01T00:00:00Z",
    "paidPromotion": false,
    "isFinancialPromotion": true,
    "variations": [
      { "fileFormat": "image", "uploadId": "<de-upload-id>", "channelIds": ["<channel-id>"], "jurisdictionId": "<de-jurisdiction-id>" },
      { "fileFormat": "image", "uploadId": "<fr-upload-id>", "channelIds": ["<channel-id>"], "jurisdictionId": "<fr-jurisdiction-id>" }
    ]
  }'

Response (201 Created):

{
  "variations": [
    { "promotionId": "promo-uuid-a", "versionId": "version-uuid-a", "version": 1, "publicId": "45-A" },
    { "promotionId": "promo-uuid-b", "versionId": "version-uuid-b", "version": 1, "publicId": "45-B" }
  ],
  "correlationId": "corr-uuid-..."
}

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

Field	Where	Notes
`promotionName`, `productIds`, `deadline`, `paidPromotion`, `isFinancialPromotion`, `evergreen`, `metadata`	Top level	Shared by every variation
`fileFormat`	Per variation	Required on each entry
`uploadId` or `content`	Per variation	`content` for `fileFormat: "text"`, otherwise a single `uploadId`
`channelIds`, `jurisdictionId`	Per variation	Each variation can target different channels and a different jurisdiction
`caption`, `details`, `linkedClaimIds`, `targetMarketIds`	Per variation	Optional

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.

POST https://public-api.adclear.ai/v1/promotions/{promotionId}/versions

{
  "uploadIds": ["<new-upload-id>"],
  "fileFormat": "pdf"
}

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

Field	Required	Description
`uploadIds`	Conditional	Upload IDs for the revised content. Required for file-based formats; omit when `fileFormat` is `"text"`
`content`	Conditional	Inline text or HTML. Required when `fileFormat` is `"text"`; omit for file-based formats
`fileFormat`	Yes	`pdf`, `image`, `video`, `audio`, `text`, or `document`
`deadline`	No	Updated deadline (ISO 8601). Retained if omitted
`caption`	No	Updated caption. Retained if omitted
`details`	No	Updated details. Retained if omitted
`type`	No	`single`, `carousel`, or `variations`. Inherited if omitted
`linkedClaimIds`	No	Updated claim IDs. Retained if omitted
`targetMarketIds`	No	Updated target market IDs. Retained if omitted
`applyToAllTargetMarkets`	No	Applies to all target markets regardless of `targetMarketIds`
`metadata`	No	Updated metadata. The original is retained and echoed in webhooks if omitted

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.

Frequently asked questions

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".

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.

For cross-cutting errors (401, 403, 429, 502), see Errors & rate limits.

Get started

Fundamentals

Adclear API

File API

Create a promotion

Metadata

Text promotions

Handling upload conflicts

Create a variation set

Shared vs per-variation fields

Submit a revision

Create-version fields

Frequently asked questions

​Create a promotion

​Metadata

​Text promotions

​Handling upload conflicts

​Create a variation set

​Shared vs per-variation fields

​Submit a revision

​Create-version fields

​Frequently asked questions

Create a promotion

Metadata

Text promotions

Handling upload conflicts

Create a variation set

Shared vs per-variation fields

Submit a revision

Create-version fields

Frequently asked questions