Skip to main content
POST
/
v1
/
promotions
Create a promotion with first version
curl --request POST \
  --url https://public-api.adclear.ai/v1/promotions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-External-User-Email: <x-external-user-email>' \
  --header 'X-External-User-ID: <x-external-user-id>' \
  --data '
{
  "fileFormat": "text",
  "promotionName": "<string>",
  "channelIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "productIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "jurisdictionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "uploadIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "content": "<string>",
  "deadline": "2023-11-07T05:31:56Z",
  "paidPromotion": true,
  "isFinancialPromotion": true,
  "evergreen": true,
  "nextReviewDate": "2023-11-07T05:31:56Z",
  "caption": "<string>",
  "details": "<string>",
  "type": "single",
  "linkedClaimIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "targetMarketIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "applyToAllTargetMarkets": true,
  "metadata": {
    "workfrontProjectId": "PROJ-123",
    "workfrontTaskId": "TASK-456",
    "workfrontDocumentId": "DOC-789"
  }
}
'
{
  "promotionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "versionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "version": 123,
  "metadata": {}
}

Authorizations

​
Authorization
string
header
required

Unkey API key passed as Bearer token

Headers

​
X-External-User-ID
string
required

External user identifier from the calling system

​
X-External-User-Email
string<email>
required

External user email from the calling system

Body

application/json
​
fileFormat
enum<string>
required

Content format (text, video, audio, image, pdf, document)

Available options:
text,
video,
audio,
image,
pdf,
document
​
promotionName
string
required

Display name for the promotion

Minimum string length: 1
​
channelIds
string<uuid>[]
required

Channel IDs (from /v1/channels)

Minimum array length: 1
​
productIds
string<uuid>[]
required

Product IDs (from /v1/products)

Minimum array length: 1
​
jurisdictionId
string<uuid>
required

Jurisdiction ID (from /v1/jurisdictions)

​
uploadIds
string<uuid>[]

Upload IDs from the File API. Required for file-based formats (pdf, image, video, etc.). Must be omitted when fileFormat is "text".

​
content
string

Inline text or HTML content. Required when fileFormat is "text". Must be omitted for file-based formats.

Minimum string length: 1
​
deadline
string<date-time>

Deadline in ISO 8601 format

​
paidPromotion
boolean

Whether this is a paid promotion

​
isFinancialPromotion
boolean

Whether this is a financial promotion

​
evergreen
boolean

Whether this promotion is evergreen (no expiry)

​
nextReviewDate
string<date-time> | null

Next review date in ISO 8601 format

​
caption
string
​
details
string
​
type
enum<string>

Promotion type (single, batch, carousel, variations)

Available options:
single,
batch,
carousel,
variations
​
linkedClaimIds
string<uuid>[]
​
targetMarketIds
string<uuid>[]
​
applyToAllTargetMarkets
boolean
​
metadata
object

Arbitrary key-value pairs stored with the promotion and echoed back in webhook payloads. Max 20 keys. Keys: alphanumeric/underscore/hyphen, max 128 chars. Values: max 1024 chars. Do not store PII, credentials, or sensitive data.

Example:
{
  "workfrontProjectId": "PROJ-123",
  "workfrontTaskId": "TASK-456",
  "workfrontDocumentId": "DOC-789"
}

Response

Promotion created

​
promotionId
string<uuid>
required
​
versionId
string<uuid>
required
​
version
integer
required

Auto-derived version number

​
metadata
object

Stored metadata echoed back for confirmation