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": "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"
},
"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": "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"
},
"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: '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'
},
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' => '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'
],
'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\": \"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 \"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\": \"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 \"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\": \"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 \"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": {
"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"
}{
"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": "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"
},
"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": "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"
},
"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: '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'
},
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' => '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'
],
'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\": \"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 \"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\": \"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 \"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\": \"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 \"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": {
"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"
}{
"error": {
"message": "<string>",
"details": [
{
"type": "field_error",
"field": "<string>",
"message": "<string>"
}
]
},
"correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}Authorizations
Unkey API key passed as Bearer token
Headers
External user identifier from the calling system
External user email from the calling system
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 in ISO 8601 format
Promotion 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?
⌘I