Skip to main content
POST
/
v1
/
promotions
Create promotion
curl --request POST \
  --url https://public-api.adclear.ai/v1/promotions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-External-User-ID: <x-external-user-id>' \
  --data '
{
  "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>",
  "linkedClaimIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "targetMarketIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "applyToAllTargetMarkets": true,
  "metadata": {
    "workfrontProjectId": "PROJ-123",
    "workfrontTaskId": "TASK-456",
    "workfrontDocumentId": "DOC-789"
  }
}
'
import requests

url = "https://public-api.adclear.ai/v1/promotions"

payload = {
    "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>",
    "linkedClaimIds": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "targetMarketIds": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "applyToAllTargetMarkets": True,
    "metadata": {
        "workfrontProjectId": "PROJ-123",
        "workfrontTaskId": "TASK-456",
        "workfrontDocumentId": "DOC-789"
    }
}
headers = {
    "X-External-User-ID": "<x-external-user-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {
    'X-External-User-ID': '<x-external-user-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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>',
    linkedClaimIds: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    targetMarketIds: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    applyToAllTargetMarkets: true,
    metadata: {
      workfrontProjectId: 'PROJ-123',
      workfrontTaskId: 'TASK-456',
      workfrontDocumentId: 'DOC-789'
    }
  })
};

fetch('https://public-api.adclear.ai/v1/promotions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://public-api.adclear.ai/v1/promotions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>',
    'linkedClaimIds' => [
        '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ],
    'targetMarketIds' => [
        '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ],
    'applyToAllTargetMarkets' => true,
    'metadata' => [
        'workfrontProjectId' => 'PROJ-123',
        'workfrontTaskId' => 'TASK-456',
        'workfrontDocumentId' => 'DOC-789'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-External-User-ID: <x-external-user-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://public-api.adclear.ai/v1/promotions"

	payload := strings.NewReader("{\n  \"promotionName\": \"<string>\",\n  \"channelIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"productIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"jurisdictionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"uploadIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"content\": \"<string>\",\n  \"deadline\": \"2023-11-07T05:31:56Z\",\n  \"paidPromotion\": true,\n  \"isFinancialPromotion\": true,\n  \"evergreen\": true,\n  \"nextReviewDate\": \"2023-11-07T05:31:56Z\",\n  \"caption\": \"<string>\",\n  \"details\": \"<string>\",\n  \"linkedClaimIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"targetMarketIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"applyToAllTargetMarkets\": true,\n  \"metadata\": {\n    \"workfrontProjectId\": \"PROJ-123\",\n    \"workfrontTaskId\": \"TASK-456\",\n    \"workfrontDocumentId\": \"DOC-789\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-External-User-ID", "<x-external-user-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://public-api.adclear.ai/v1/promotions")
  .header("X-External-User-ID", "<x-external-user-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"promotionName\": \"<string>\",\n  \"channelIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"productIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"jurisdictionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"uploadIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"content\": \"<string>\",\n  \"deadline\": \"2023-11-07T05:31:56Z\",\n  \"paidPromotion\": true,\n  \"isFinancialPromotion\": true,\n  \"evergreen\": true,\n  \"nextReviewDate\": \"2023-11-07T05:31:56Z\",\n  \"caption\": \"<string>\",\n  \"details\": \"<string>\",\n  \"linkedClaimIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"targetMarketIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"applyToAllTargetMarkets\": true,\n  \"metadata\": {\n    \"workfrontProjectId\": \"PROJ-123\",\n    \"workfrontTaskId\": \"TASK-456\",\n    \"workfrontDocumentId\": \"DOC-789\"\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://public-api.adclear.ai/v1/promotions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-External-User-ID"] = '<x-external-user-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"promotionName\": \"<string>\",\n  \"channelIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"productIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"jurisdictionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"uploadIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"content\": \"<string>\",\n  \"deadline\": \"2023-11-07T05:31:56Z\",\n  \"paidPromotion\": true,\n  \"isFinancialPromotion\": true,\n  \"evergreen\": true,\n  \"nextReviewDate\": \"2023-11-07T05:31:56Z\",\n  \"caption\": \"<string>\",\n  \"details\": \"<string>\",\n  \"linkedClaimIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"targetMarketIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"applyToAllTargetMarkets\": true,\n  \"metadata\": {\n    \"workfrontProjectId\": \"PROJ-123\",\n    \"workfrontTaskId\": \"TASK-456\",\n    \"workfrontDocumentId\": \"DOC-789\"\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "promotionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "versionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "version": 123,
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": {}
}
{
  "error": {
    "message": "<string>",
    "details": [
      {
        "type": "field_error",
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
{
  "error": {
    "message": "<string>",
    "details": [
      {
        "type": "field_error",
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
{
  "error": {
    "message": "<string>",
    "details": [
      {
        "type": "field_error",
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
{
  "error": {
    "message": "<string>",
    "details": [
      {
        "type": "field_error",
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
{
  "error": {
    "message": "<string>",
    "details": [
      {
        "type": "field_error",
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

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>

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

​
correlationId
string<uuid>
required

Correlation ID for request tracing. Include in support requests.

​
metadata
object

Stored metadata echoed back for confirmation