Create version
curl --request POST \
--url https://public-api.adclear.ai/v1/promotions/{promotionId}/versions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-External-User-ID: <x-external-user-id>' \
--data '
{
"uploadIds": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
],
"content": "<string>",
"deadline": "<string>",
"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"
},
"tags": [
"Q1 Campaign",
"retail"
]
}
'import requests
url = "https://public-api.adclear.ai/v1/promotions/{promotionId}/versions"
payload = {
"uploadIds": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
"content": "<string>",
"deadline": "<string>",
"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"
},
"tags": ["Q1 Campaign", "retail"]
}
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({
uploadIds: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
content: '<string>',
deadline: '<string>',
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'
},
tags: ['Q1 Campaign', 'retail']
})
};
fetch('https://public-api.adclear.ai/v1/promotions/{promotionId}/versions', 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/{promotionId}/versions",
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([
'uploadIds' => [
'3c90c3cc-0d44-4b50-8888-8dd25736052a'
],
'content' => '<string>',
'deadline' => '<string>',
'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'
],
'tags' => [
'Q1 Campaign',
'retail'
]
]),
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/{promotionId}/versions"
payload := strings.NewReader("{\n \"uploadIds\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"content\": \"<string>\",\n \"deadline\": \"<string>\",\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 \"tags\": [\n \"Q1 Campaign\",\n \"retail\"\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/{promotionId}/versions")
.header("X-External-User-ID", "<x-external-user-id>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"uploadIds\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"content\": \"<string>\",\n \"deadline\": \"<string>\",\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 \"tags\": [\n \"Q1 Campaign\",\n \"retail\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://public-api.adclear.ai/v1/promotions/{promotionId}/versions")
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 \"uploadIds\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"content\": \"<string>\",\n \"deadline\": \"<string>\",\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 \"tags\": [\n \"Q1 Campaign\",\n \"retail\"\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": {},
"tags": [
"<string>"
]
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}Promotions
Create version
Creates a new version. Inherits promotionName, channel, product, and jurisdiction from the existing promotion. For file-based formats, provide uploadIds. For text format, provide inline content instead. Returns 409 if any referenced upload has not finished uploading to storage.
POST
/
v1
/
promotions
/
{promotionId}
/
versions
Create version
curl --request POST \
--url https://public-api.adclear.ai/v1/promotions/{promotionId}/versions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-External-User-ID: <x-external-user-id>' \
--data '
{
"uploadIds": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
],
"content": "<string>",
"deadline": "<string>",
"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"
},
"tags": [
"Q1 Campaign",
"retail"
]
}
'import requests
url = "https://public-api.adclear.ai/v1/promotions/{promotionId}/versions"
payload = {
"uploadIds": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
"content": "<string>",
"deadline": "<string>",
"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"
},
"tags": ["Q1 Campaign", "retail"]
}
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({
uploadIds: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
content: '<string>',
deadline: '<string>',
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'
},
tags: ['Q1 Campaign', 'retail']
})
};
fetch('https://public-api.adclear.ai/v1/promotions/{promotionId}/versions', 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/{promotionId}/versions",
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([
'uploadIds' => [
'3c90c3cc-0d44-4b50-8888-8dd25736052a'
],
'content' => '<string>',
'deadline' => '<string>',
'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'
],
'tags' => [
'Q1 Campaign',
'retail'
]
]),
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/{promotionId}/versions"
payload := strings.NewReader("{\n \"uploadIds\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"content\": \"<string>\",\n \"deadline\": \"<string>\",\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 \"tags\": [\n \"Q1 Campaign\",\n \"retail\"\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/{promotionId}/versions")
.header("X-External-User-ID", "<x-external-user-id>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"uploadIds\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"content\": \"<string>\",\n \"deadline\": \"<string>\",\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 \"tags\": [\n \"Q1 Campaign\",\n \"retail\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://public-api.adclear.ai/v1/promotions/{promotionId}/versions")
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 \"uploadIds\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"content\": \"<string>\",\n \"deadline\": \"<string>\",\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 \"tags\": [\n \"Q1 Campaign\",\n \"retail\"\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": {},
"tags": [
"<string>"
]
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}Authorizations
API key passed as Bearer token
Headers
Identifier of the acting user in the calling system (e.g. a Workfront user id). Recorded against every audited action this request performs.
Acting user email. Only meaningful on keys with act-on-behalf enabled, where it is resolved to the matching Adclear user and is mandatory on writes. Ignored on ordinary keys.
Path Parameters
Promotion ID
Body
application/json
Content format (text, video, audio, image, pdf, document)
Available options:
text, video, audio, image, pdf, document Upload IDs from the File API. Required for file-based formats (pdf, image, video, etc.). Must be omitted when fileFormat is "text".
Inline text or HTML content. Required when fileFormat is "text". Must be omitted for file-based formats.
Minimum string length:
1Deadline as YYYY-MM-DD calendar date or ISO 8601 datetime
Additional reviewer context for the promotion (shown as "Additional details" in the Adclear UI). Free text, up to 1500 characters.
Maximum string length:
1500Promotion type (single, batch, carousel, variations)
Available options:
single, batch, carousel, variations 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.
Show child attributes
Show child attributes
Example:
{
"workfrontProjectId": "PROJ-123",
"workfrontTaskId": "TASK-456",
"workfrontDocumentId": "DOC-789"
}
Tag names to attach to the promotion. Existing tags are reused; unknown names are created. Names are trimmed, and duplicates within one request are ignored. Tags belong to the promotion, so they are shared by all of its versions. Max 20 tags, each up to 255 characters. Names beginning with "Var-" and the name "TESTING" are reserved.
Example:
["Q1 Campaign", "retail"]
Response
Version created
Auto-derived version number
Correlation ID for request tracing. Include in support requests.
Stored metadata echoed back for confirmation
Show child attributes
Show child attributes
Tag names actually attached, echoed back for confirmation. Empty when tags were requested but could not be attached — the promotion is still created, and the request can be retried by adding the tags separately.
Was this page helpful?