Skip to main content

​
Create a Promotion

Request (to the Integration API): 
POST https://public-api.adclear.ai/v1/promotions

{
  "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"
  }
}

​
Text Promotions

When fileFormat is "text", provide the content field instead of uploadIds. The content field accepts plain text or HTML. Do not provide uploadIds for text promotions. 
POST https://public-api.adclear.ai/v1/promotions

{
  "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>",
  "metadata": {
    "workfrontProjectId": "PROJ-789"
  }
}

​
Handling Upload Conflicts

If the file hasn’t finished uploading (409 Conflict): 
{
  "error": {
    "code": "CONFLICT",
    "message": "One or more uploads are not ready",
    "details": [
      { "type": "upload_not_ready", "uploadId": "a1b2c3d4-..." }
    ]
  },
  "correlationId": "corr-uuid-..."
}
Implement a retry with exponential back-off (e.g. 1s, 2s, 4s up to ~30s). Small files typically complete within seconds; larger files (100MB+) may take longer.

​
About Metadata

The metadata field accepts an arbitrary string-to-string map. Use it to pass through your own reference IDs (e.g. Workfront project/task IDs, JIRA keys, campaign identifiers). It is stored with the promotion and echoed back in every webhook payload, so you can correlate Adclear events back to your system without maintaining a separate mapping.

​
Submit a Revision

If the promotion needs changes after review, upload new files and create a new version on the same promotion. The new version inherits the promotion’s name, channels, products, and jurisdiction. You only need to supply the new files and any fields you want to override. Upload the revised file(s) first (see File Upload), then: Request: 
POST https://public-api.adclear.ai/v1/promotions/{promotionId}/versions

{
  "uploadIds": ["<new-upload-id>"],
  "fileFormat": "pdf"
}
Response (201 Created): 
{
  "promotionId": "promo-uuid-...",
  "versionId": "new-version-uuid-...",
  "version": 2,
  "metadata": {
    "workfrontProjectId": "PROJ-123",
    "workfrontTaskId": "TASK-456"
  }
}

​
Create Version Request Fields

FieldRequiredDescription
uploadIdsConditionalOne or more upload IDs for the revised content. Required for file-based formats; must be omitted when fileFormat is "text"
contentConditionalInline text or HTML content. Required when fileFormat is "text"; must be omitted for file-based formats
fileFormatYesContent format: pdf, image, video, audio, text, document
deadlineNoUpdated deadline (ISO 8601). If omitted, the existing deadline is retained
captionNoUpdated caption. If omitted, the existing value is retained
detailsNoUpdated details/notes. If omitted, the existing value is retained
typeNoPromotion type: single, batch, carousel, variations. If omitted, inherited
linkedClaimIdsNoUpdated claim IDs. If omitted, existing links are retained
targetMarketIdsNoUpdated target market IDs. If omitted, existing values are retained
applyToAllTargetMarketsNoIf true, applies to all target markets regardless of targetMarketIds
metadataNoUpdated metadata. If omitted, the original metadata from promotion creation is retained and continues to be echoed in webhooks

​
What is Inherited vs. What Can Change

  • Always inherited (set once at promotion creation, cannot be changed per-version): promotionName, channelIds, productIds, jurisdictionId
  • Overridable per-version: all optional fields listed above. If you omit them, the values from the previous version carry forward.
Then trigger evaluation on the new version. Each version is independently evaluated. Previous version results are retained for audit purposes.