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

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" }
  }'
Response (201 Created): 
{
  "promotionId": "promo-uuid-...",
  "versionId": "version-uuid-...",
  "version": 1,
  "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.

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

​
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

FieldRequiredDescription
uploadIdsConditionalUpload IDs for the revised content. Required for file-based formats; omit when fileFormat is "text"
contentConditionalInline text or HTML. Required when fileFormat is "text"; omit for file-based formats
fileFormatYespdf, image, video, audio, text, or document
deadlineNoUpdated deadline (ISO 8601). Retained if omitted
captionNoUpdated caption. Retained if omitted
detailsNoUpdated details. Retained if omitted
typeNosingle, batch, carousel, or variations. Inherited if omitted
linkedClaimIdsNoUpdated claim IDs. Retained if omitted
targetMarketIdsNoUpdated target market IDs. Retained if omitted
applyToAllTargetMarketsNoApplies to all target markets regardless of targetMarketIds
metadataNoUpdated 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

File typefileFormat
.pdfpdf
.jpg, .png, .gif, .webp, .svg, .bmp, .tiffimage
.mp4, .mov, .avi, .webm, .mkv, .wmvvideo
.mp3, .wav, .aac, .ogg, .flac, .m4aaudio
.doc, .docx, .xls, .xlsx, .ppt, .pptx, .txt, .csv, .rtfdocument
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".
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.