Boost post as ad
curl --request POST \
--url https://api.aisa.one/apis/v1/ads/boost \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"adAccountId": "act_757082720485182",
"callToAction": "WHATSAPP_MESSAGE",
"goal": "engagement",
"name": "WhatsApp post boost",
"platformPostId": "811889972008357_123456789"
}
'import requests
url = "https://api.aisa.one/apis/v1/ads/boost"
payload = {
"adAccountId": "act_757082720485182",
"callToAction": "WHATSAPP_MESSAGE",
"goal": "engagement",
"name": "WhatsApp post boost",
"platformPostId": "811889972008357_123456789"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
adAccountId: 'act_757082720485182',
callToAction: 'WHATSAPP_MESSAGE',
goal: 'engagement',
name: 'WhatsApp post boost',
platformPostId: '811889972008357_123456789'
})
};
fetch('https://api.aisa.one/apis/v1/ads/boost', 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://api.aisa.one/apis/v1/ads/boost",
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([
'adAccountId' => 'act_757082720485182',
'callToAction' => 'WHATSAPP_MESSAGE',
'goal' => 'engagement',
'name' => 'WhatsApp post boost',
'platformPostId' => '811889972008357_123456789'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://api.aisa.one/apis/v1/ads/boost"
payload := strings.NewReader("{\n \"adAccountId\": \"act_757082720485182\",\n \"callToAction\": \"WHATSAPP_MESSAGE\",\n \"goal\": \"engagement\",\n \"name\": \"WhatsApp post boost\",\n \"platformPostId\": \"811889972008357_123456789\"\n}")
req, _ := http.NewRequest("POST", url, payload)
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://api.aisa.one/apis/v1/ads/boost")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"adAccountId\": \"act_757082720485182\",\n \"callToAction\": \"WHATSAPP_MESSAGE\",\n \"goal\": \"engagement\",\n \"name\": \"WhatsApp post boost\",\n \"platformPostId\": \"811889972008357_123456789\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.aisa.one/apis/v1/ads/boost")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"adAccountId\": \"act_757082720485182\",\n \"callToAction\": \"WHATSAPP_MESSAGE\",\n \"goal\": \"engagement\",\n \"name\": \"WhatsApp post boost\",\n \"platformPostId\": \"811889972008357_123456789\"\n}"
response = http.request(request)
puts response.read_body{
"message": "<string>",
"results": [
{
"node": "campaign",
"reason": "<string>",
"status": "validated"
}
],
"validateOnly": true
}{
"ad": {
"_id": "<string>",
"adSetName": "<string>",
"adType": "boost",
"bidAmount": 123,
"bidStrategy": "LOWEST_COST_WITHOUT_CAP",
"budget": {
"amount": 123,
"daily": 123,
"lifetime": 123,
"pacing": "<string>",
"type": "daily"
},
"campaignName": "<string>",
"configuredStatus": "<string>",
"costType": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"creative": {
"adFormat": "<string>",
"assetGroup": {
"businessName": "<string>",
"descriptions": [
"<string>"
],
"finalUrl": "<string>",
"headlines": [
"<string>"
],
"images": {},
"longHeadline": "<string>",
"name": "<string>",
"youtubeVideoId": "<string>"
},
"assetGroupResourceName": "<string>",
"assetResourceName": "<string>",
"assets": {
"marketingImages": [
{}
],
"squareMarketingImages": [
{}
]
},
"bodies": [
"<string>"
],
"body": "<string>",
"callToAction": "<string>",
"carouselCards": [
{}
],
"catalog": {
"format": "single_image",
"formatTransformationSpec": [
{}
],
"productSetId": "<string>"
},
"creativeFeatures": {},
"creativeId": "<string>",
"description": "<string>",
"descriptions": [
"<string>"
],
"effectiveInstagramMediaId": "<string>",
"effectiveObjectStoryId": "<string>",
"finalUrls": [
"<string>"
],
"googleDescription": "<string>",
"googleHeadline": "<string>",
"headline": "<string>",
"headlines": [
"<string>"
],
"imageHash": "<string>",
"imageUrl": "<string>",
"instagramPermalinkUrl": "<string>",
"instagramUserId": "<string>",
"instagramVideoFallback": {
"kind": "instagram_video_reuploaded",
"linkedToOriginalPost": true,
"platformError": {},
"videoId": "<string>"
},
"isServing": true,
"leadGenFormId": "<string>",
"linkUrl": "<string>",
"mediaUrls": [
"<string>"
],
"objectStoryId": "<string>",
"objectType": "<string>",
"pageId": "<string>",
"pinterestDescription": "<string>",
"pinterestImageUrl": "<string>",
"pinterestTitle": "<string>",
"servingHoldReasons": [
"<string>"
],
"thumbnailUrl": "<string>",
"urlTags": "<string>",
"videoId": "<string>",
"videoUrl": "<string>",
"whatsappPhoneNumber": "<string>",
"youtubeVideoIds": [
"<string>"
]
},
"creativeType": "carousel",
"goal": "engagement",
"isExternal": true,
"metrics": {
"actionValues": {},
"actions": {},
"allConversions": 123,
"clicks": 123,
"conversions": 123,
"costPerAction": {},
"costPerConversion": 123,
"costPerThruplay": 123,
"cpc": 123,
"cpm": 123,
"ctr": 123,
"engagement": 123,
"engagementBreakdown": {
"comments": 123,
"linkClicks": 123,
"pageEngagement": 123,
"pageLikes": 123,
"postEngagement": 123,
"reactions": 123,
"saves": 123,
"shares": 123,
"videoViews": 123
},
"funnel": {
"appInstalls": 123,
"cartAdds": 123,
"checkoutsInitiated": 123,
"contentViews": 123,
"landingPageViews": 123,
"leads": 123,
"messagingConversationsStarted": 123,
"messagingFirstReplies": 123,
"paymentInfoAdds": 123,
"purchases": 123,
"registrationsCompleted": 123,
"searches": 123,
"wishlistAdds": 123
},
"impressions": 123,
"inlineLinkClickCtr": 123,
"inlineLinkClicks": 123,
"lastSyncedAt": "2023-11-07T05:31:56Z",
"outboundClicks": 123,
"outboundClicksCtr": 123,
"purchaseValue": 123,
"reach": 123,
"roas": 123,
"spend": 123,
"uniqueClicks": 123,
"uniqueCtr": 123,
"video2SecWatchedActions": 123,
"video30SecWatchedActions": 123,
"video6SecFocusedViews": 123,
"video6SecWatchedActions": 123,
"videoAvgTimeWatchedActions": 123,
"videoP100WatchedActions": 123,
"videoP25WatchedActions": 123,
"videoP50WatchedActions": 123,
"videoP75WatchedActions": 123,
"videoP95WatchedActions": 123,
"videoPlayActions": 123,
"videoThruplayWatchedActions": 123
},
"name": "<string>",
"optimizationGoal": "<string>",
"platform": "facebook",
"platformAdAccountId": "<string>",
"platformAdAccountName": "<string>",
"platformAdId": "<string>",
"platformAdSetId": "<string>",
"platformCampaignId": "<string>",
"platformCreatedAt": "2023-11-07T05:31:56Z",
"platformObjective": "<string>",
"promotedObject": {
"application_id": "<string>",
"custom_event_type": "<string>",
"page_id": "<string>",
"pixel_id": "<string>",
"product_set_id": "<string>"
},
"rejectionReason": "<string>",
"reviewStatus": "in_review",
"roasAverageFloor": 123,
"schedule": {
"endDate": "2023-11-07T05:31:56Z",
"startDate": "2023-11-07T05:31:56Z"
},
"servingStatuses": [
"<string>"
],
"status": "active",
"synced": true,
"targeting": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"instagramVideoFallback": {
"kind": "instagram_video_reuploaded",
"linkedToOriginalPost": true,
"platformError": {
"message": "<string>",
"code": 123,
"fbtraceId": "<string>",
"subcode": 123
},
"videoId": "<string>"
},
"message": "<string>",
"warnings": [
"<string>"
]
}{
"error": {
"code": "<string>",
"details": {},
"message": "<string>",
"param": "<string>",
"retryHint": "<string>",
"retryable": true,
"type": "<string>"
}
}AIsa Ads
Boost post as ad
Ad Campaigns. Can spend money or change spend: needs the ads:spend scope and X-Aisa-Confirm: spend; without the header the request is refused with confirmation_required and nothing is sent. Boosts a published post as an ad that spends the given budget. validateOnly=true checks the request without acting and needs no confirmation. Turns an already published post into a paid ad that keeps the post's likes and comments, creating the campaign around it. By default it provisions the whole hierarchy (campaign, ad set, ad). ### Attach shape (Meta) Send `adSetId` to put the ad under an EXISTING ad set instead, so that ad set keeps its learning phase. That ad set then owns `budget`, `schedule` and `targeting`.
<!-- aisa-pricing:start -->
A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.
<!-- aisa-pricing:end -->
POST
https://api.aisa.one
/
apis
/
v1
/
ads
/
boost
Boost post as ad
curl --request POST \
--url https://api.aisa.one/apis/v1/ads/boost \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"adAccountId": "act_757082720485182",
"callToAction": "WHATSAPP_MESSAGE",
"goal": "engagement",
"name": "WhatsApp post boost",
"platformPostId": "811889972008357_123456789"
}
'import requests
url = "https://api.aisa.one/apis/v1/ads/boost"
payload = {
"adAccountId": "act_757082720485182",
"callToAction": "WHATSAPP_MESSAGE",
"goal": "engagement",
"name": "WhatsApp post boost",
"platformPostId": "811889972008357_123456789"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
adAccountId: 'act_757082720485182',
callToAction: 'WHATSAPP_MESSAGE',
goal: 'engagement',
name: 'WhatsApp post boost',
platformPostId: '811889972008357_123456789'
})
};
fetch('https://api.aisa.one/apis/v1/ads/boost', 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://api.aisa.one/apis/v1/ads/boost",
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([
'adAccountId' => 'act_757082720485182',
'callToAction' => 'WHATSAPP_MESSAGE',
'goal' => 'engagement',
'name' => 'WhatsApp post boost',
'platformPostId' => '811889972008357_123456789'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://api.aisa.one/apis/v1/ads/boost"
payload := strings.NewReader("{\n \"adAccountId\": \"act_757082720485182\",\n \"callToAction\": \"WHATSAPP_MESSAGE\",\n \"goal\": \"engagement\",\n \"name\": \"WhatsApp post boost\",\n \"platformPostId\": \"811889972008357_123456789\"\n}")
req, _ := http.NewRequest("POST", url, payload)
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://api.aisa.one/apis/v1/ads/boost")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"adAccountId\": \"act_757082720485182\",\n \"callToAction\": \"WHATSAPP_MESSAGE\",\n \"goal\": \"engagement\",\n \"name\": \"WhatsApp post boost\",\n \"platformPostId\": \"811889972008357_123456789\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.aisa.one/apis/v1/ads/boost")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"adAccountId\": \"act_757082720485182\",\n \"callToAction\": \"WHATSAPP_MESSAGE\",\n \"goal\": \"engagement\",\n \"name\": \"WhatsApp post boost\",\n \"platformPostId\": \"811889972008357_123456789\"\n}"
response = http.request(request)
puts response.read_body{
"message": "<string>",
"results": [
{
"node": "campaign",
"reason": "<string>",
"status": "validated"
}
],
"validateOnly": true
}{
"ad": {
"_id": "<string>",
"adSetName": "<string>",
"adType": "boost",
"bidAmount": 123,
"bidStrategy": "LOWEST_COST_WITHOUT_CAP",
"budget": {
"amount": 123,
"daily": 123,
"lifetime": 123,
"pacing": "<string>",
"type": "daily"
},
"campaignName": "<string>",
"configuredStatus": "<string>",
"costType": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"creative": {
"adFormat": "<string>",
"assetGroup": {
"businessName": "<string>",
"descriptions": [
"<string>"
],
"finalUrl": "<string>",
"headlines": [
"<string>"
],
"images": {},
"longHeadline": "<string>",
"name": "<string>",
"youtubeVideoId": "<string>"
},
"assetGroupResourceName": "<string>",
"assetResourceName": "<string>",
"assets": {
"marketingImages": [
{}
],
"squareMarketingImages": [
{}
]
},
"bodies": [
"<string>"
],
"body": "<string>",
"callToAction": "<string>",
"carouselCards": [
{}
],
"catalog": {
"format": "single_image",
"formatTransformationSpec": [
{}
],
"productSetId": "<string>"
},
"creativeFeatures": {},
"creativeId": "<string>",
"description": "<string>",
"descriptions": [
"<string>"
],
"effectiveInstagramMediaId": "<string>",
"effectiveObjectStoryId": "<string>",
"finalUrls": [
"<string>"
],
"googleDescription": "<string>",
"googleHeadline": "<string>",
"headline": "<string>",
"headlines": [
"<string>"
],
"imageHash": "<string>",
"imageUrl": "<string>",
"instagramPermalinkUrl": "<string>",
"instagramUserId": "<string>",
"instagramVideoFallback": {
"kind": "instagram_video_reuploaded",
"linkedToOriginalPost": true,
"platformError": {},
"videoId": "<string>"
},
"isServing": true,
"leadGenFormId": "<string>",
"linkUrl": "<string>",
"mediaUrls": [
"<string>"
],
"objectStoryId": "<string>",
"objectType": "<string>",
"pageId": "<string>",
"pinterestDescription": "<string>",
"pinterestImageUrl": "<string>",
"pinterestTitle": "<string>",
"servingHoldReasons": [
"<string>"
],
"thumbnailUrl": "<string>",
"urlTags": "<string>",
"videoId": "<string>",
"videoUrl": "<string>",
"whatsappPhoneNumber": "<string>",
"youtubeVideoIds": [
"<string>"
]
},
"creativeType": "carousel",
"goal": "engagement",
"isExternal": true,
"metrics": {
"actionValues": {},
"actions": {},
"allConversions": 123,
"clicks": 123,
"conversions": 123,
"costPerAction": {},
"costPerConversion": 123,
"costPerThruplay": 123,
"cpc": 123,
"cpm": 123,
"ctr": 123,
"engagement": 123,
"engagementBreakdown": {
"comments": 123,
"linkClicks": 123,
"pageEngagement": 123,
"pageLikes": 123,
"postEngagement": 123,
"reactions": 123,
"saves": 123,
"shares": 123,
"videoViews": 123
},
"funnel": {
"appInstalls": 123,
"cartAdds": 123,
"checkoutsInitiated": 123,
"contentViews": 123,
"landingPageViews": 123,
"leads": 123,
"messagingConversationsStarted": 123,
"messagingFirstReplies": 123,
"paymentInfoAdds": 123,
"purchases": 123,
"registrationsCompleted": 123,
"searches": 123,
"wishlistAdds": 123
},
"impressions": 123,
"inlineLinkClickCtr": 123,
"inlineLinkClicks": 123,
"lastSyncedAt": "2023-11-07T05:31:56Z",
"outboundClicks": 123,
"outboundClicksCtr": 123,
"purchaseValue": 123,
"reach": 123,
"roas": 123,
"spend": 123,
"uniqueClicks": 123,
"uniqueCtr": 123,
"video2SecWatchedActions": 123,
"video30SecWatchedActions": 123,
"video6SecFocusedViews": 123,
"video6SecWatchedActions": 123,
"videoAvgTimeWatchedActions": 123,
"videoP100WatchedActions": 123,
"videoP25WatchedActions": 123,
"videoP50WatchedActions": 123,
"videoP75WatchedActions": 123,
"videoP95WatchedActions": 123,
"videoPlayActions": 123,
"videoThruplayWatchedActions": 123
},
"name": "<string>",
"optimizationGoal": "<string>",
"platform": "facebook",
"platformAdAccountId": "<string>",
"platformAdAccountName": "<string>",
"platformAdId": "<string>",
"platformAdSetId": "<string>",
"platformCampaignId": "<string>",
"platformCreatedAt": "2023-11-07T05:31:56Z",
"platformObjective": "<string>",
"promotedObject": {
"application_id": "<string>",
"custom_event_type": "<string>",
"page_id": "<string>",
"pixel_id": "<string>",
"product_set_id": "<string>"
},
"rejectionReason": "<string>",
"reviewStatus": "in_review",
"roasAverageFloor": 123,
"schedule": {
"endDate": "2023-11-07T05:31:56Z",
"startDate": "2023-11-07T05:31:56Z"
},
"servingStatuses": [
"<string>"
],
"status": "active",
"synced": true,
"targeting": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"instagramVideoFallback": {
"kind": "instagram_video_reuploaded",
"linkedToOriginalPost": true,
"platformError": {
"message": "<string>",
"code": 123,
"fbtraceId": "<string>",
"subcode": 123
},
"videoId": "<string>"
},
"message": "<string>",
"warnings": [
"<string>"
]
}{
"error": {
"code": "<string>",
"details": {},
"message": "<string>",
"param": "<string>",
"retryHint": "<string>",
"retryable": true,
"type": "<string>"
}
}Request contract
- Method and path: POST /apis/v1/ads/boost
- Availability: enabled
- Request URL template:
https://api.aisa.one/apis/v1/ads/boost - connectionId: query; required
- X-Aisa-Confirm: header; optional
- Idempotency-Key: header; optional
- Runtime facts: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09
{
"operationId": "post_aisa_ads_apis_v1_ads_boost",
"method": "POST",
"path": "/apis/v1/ads/boost",
"servers": [
{
"url": "https://api.aisa.one"
}
],
"parameters": [
{
"description": "The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.",
"in": "query",
"name": "connectionId",
"required": true,
"schema": {
"pattern": "^adc_[0-9A-Za-z]+$",
"type": "string"
}
},
{
"description": "Required with the value \"spend\" when the request can spend money or change spend. Without it the request is refused with 409 confirmation_required, which describes what would happen; nothing is sent to the ad platform.",
"in": "header",
"name": "X-Aisa-Confirm",
"required": false,
"schema": {
"enum": [
"spend"
],
"type": "string"
}
},
{
"description": "Passed to the ad platform integration: a retry with the same key returns the first result instead of acting twice. AIsa never retries a write for you.",
"in": "header",
"name": "Idempotency-Key",
"required": false,
"schema": {
"maxLength": 191,
"minLength": 1,
"type": "string"
}
}
],
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"content": {
"application/json": {
"example": {
"adAccountId": "act_757082720485182",
"budget": {
"amount": 2.61,
"type": "daily"
},
"callToAction": "WHATSAPP_MESSAGE",
"connectionId": "adc_7f3k2m9q",
"goal": "engagement",
"name": "WhatsApp post boost",
"platformPostId": "811889972008357_123456789",
"status": "PAUSED",
"whatsappPhoneNumber": "+12025550123"
},
"schema": {
"additionalProperties": true,
"properties": {
"adAccountId": {
"description": "Platform ad account ID",
"type": "string"
},
"adSetId": {
"description": "Meta, or TikTok with `smartPlus: true`. Attach the boosted post to this existing ad set instead of creating a campaign. Meta: the ad set then owns budget, schedule and targeting; sending those too is a 400. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.",
"type": "string"
},
"adSetName": {
"description": "Exact name for the ad-group level this boost provisions. Omitted keeps the default ` - Ad Group`. Meta: ad set; TikTok, Pinterest, Google: ad group; X: line item; LinkedIn: the campaign under the campaign group.",
"maxLength": 255,
"type": "string"
},
"adSetStatus": {
"description": "Every platform, same semantics as POST /apis/v1/ads/create. Sets the switch of the new ad set alone and overrides `status` for it. Omitted, it follows `status`.",
"enum": [
"ACTIVE",
"PAUSED"
],
"type": "string"
},
"adStatus": {
"description": "Request-side publish switch for `adStatus` on ad creation endpoints only (`status`, `campaignStatus` and `adSetStatus` carry their own inline ACTIVE/PAUSED enum there; the status-update endpoints are a separate lowercase `active`/`paused`…",
"enum": [
"ACTIVE",
"PAUSED"
],
"type": "string"
},
"attributionSpec": {
"description": "Meta only. Ad-set attribution windows, same shape as POST /apis/v1/ads/create.",
"items": {
"properties": {
"eventType": {
"enum": [
"CLICK_THROUGH",
"VIEW_THROUGH",
"ENGAGED_VIDEO_VIEW"
],
"type": "string"
},
"windowDays": {
"enum": [
1,
7,
28
],
"type": "integer"
}
},
"required": [
"eventType",
"windowDays"
],
"type": "object"
},
"maxItems": 3,
"minItems": 1,
"type": "array"
},
"bidAmount": {
"description": "Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400.",
"type": "number"
},
"bidStrategy": {
"description": "Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400.",
"enum": [
"LOWEST_COST_WITHOUT_CAP",
"LOWEST_COST_WITH_BID_CAP",
"COST_CAP",
"LOWEST_COST_WITH_MIN_ROAS"
],
"type": "string"
},
"bodies": {
"description": "Meta only. Extra primary-text options Meta rotates on the boosted post (asset_feed_spec.bodies with DEGREES_OF_FREEDOM). The post keeps its own text as one of the options. Works for Facebook posts and Instagram media.",
"items": {
"type": "string"
},
"maxItems": 5,
"minItems": 1,
"type": "array"
},
"budget": {
"description": "Alias of budgetAmount + budgetType, kept for existing callers",
"properties": {
"amount": {
"description": "Minimum varies: TikTok=$20, Pinterest=$5, others=$1",
"type": "number"
},
"type": {
"enum": [
"daily",
"lifetime"
],
"type": "string"
}
},
"required": [
"amount",
"type"
],
"type": "object"
},
"budgetAmount": {
"description": "Budget in whole currency units, the same flat field as POST /apis/v1/ads/create. Required unless adSetId is set. Minimum varies: TikTok=$20, Pinterest=$5, others=$1",
"type": "number"
},
"budgetLevel": {
"description": "Meta only, same semantics as POST /apis/v1/ads/create: campaign = Advantage campaign budget (CBO), the budget and bid strategy sit on the campaign and the ad set inherits them. Default adset. Not allowed with adSetId.",
"enum": [
"adset",
"campaign"
],
"type": "string"
},
"budgetType": {
"description": "Goes together with budgetAmount. lifetime requires schedule.endDate.",
"enum": [
"daily",
"lifetime"
],
"type": "string"
},
"callToAction": {
"description": "CTA button label. Non-messaging CTAs require `linkUrl`. WHATSAPP_MESSAGE, MESSAGE_PAGE, and INSTAGRAM_MESSAGE do not require a URL and reject linkUrl.",
"type": "string"
},
"campaignName": {
"description": "Exact name for the campaign this boost provisions. Omitted keeps the default ` - Campaign`. Every platform: on LinkedIn it names the campaign group. Ignored on the Meta attach shape (`adSetId`), which creates no campaign.",
"maxLength": 255,
"type": "string"
},
"campaignStatus": {
"description": "Every platform, same semantics as POST /apis/v1/ads/create. Sets the switch of the new campaign alone (LinkedIn: the campaign group) and overrides `status` for it. When omitted, it follows `status`.",
"enum": [
"ACTIVE",
"PAUSED"
],
"type": "string"
},
"connectionId": {
"description": "The ads connection (adc_...), when not sent as the connectionId query parameter.",
"pattern": "^adc_[0-9A-Za-z]+$",
"type": "string"
},
"creativeFeatures": {
"additionalProperties": {
"enum": [
"OPT_IN",
"OPT_OUT"
],
"type": "string"
},
"description": "Meta Advantage+ creative enhancements. Map snake_case feature names to OPT_IN or OPT_OUT; Meta validates supported keys and unspecified features default to OPT_OUT.",
"type": "object"
},
"currency": {
"description": "ISO 4217 currency code matching the ad account's currency. Meta only.",
"maxLength": 3,
"minLength": 3,
"type": "string"
},
"destinationType": {
"description": "Meta only. Ad-set destination_type: where the click LANDS, as opposed to instagramAccountId which is who the ad runs as. Independent of plain link CTAs and their goal.",
"enum": [
"INSTAGRAM_PROFILE",
"WEBSITE",
"ON_AD",
"MESSENGER",
"WHATSAPP",
"INSTAGRAM_DIRECT"
],
"type": "string"
},
"dsaBeneficiary": {
"description": "Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26).",
"maxLength": 100,
"type": "string"
},
"dsaPayor": {
"description": "Legal entity that pays for the ad. Can differ from `dsaBeneficiary` (for example, an agency paying for a client's ads). Same rules as `dsaBeneficiary`: required for EU targeting unless the ad account has a default payor.",
"maxLength": 100,
"type": "string"
},
"endDate": {
"description": "Ad-set end time (ISO 8601). Required for lifetime budgets. Same field as on POST /apis/v1/ads/create. Maps to the ad set's `end_time` (on X, the line item's `end_time`; X campaigns carry no flight dates).",
"format": "date-time",
"type": "string"
},
"existingCampaignId": {
"description": "TikTok only. Create the ad group and the Spark ad under this existing TikTok campaign instead of creating a new campaign. The campaign keeps its own status and objective (the objective must fit `goal`). Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.",
"type": "string"
},
"goal": {
"description": "Available goals vary by platform. Meta (Facebook/Instagram) and TikTok support all 7. LinkedIn supports all except app_promotion. X supports engagement, traffic, awareness, video_views, app_promotion.",
"enum": [
"engagement",
"traffic",
"awareness",
"video_views",
"lead_generation",
"conversions",
"app_promotion"
],
"type": "string"
},
"identityId": {
"description": "TikTok only. The identity the ad runs as (the profile shown on the ad), from GET /apis/v1/ads/tiktok-identities. Default: the connected TikTok account's own identity.",
"type": "string"
},
"identityType": {
"description": "TikTok only. Type of identityId; resolved from the advertiser's identity list when omitted.",
"enum": [
"TT_USER",
"CUSTOMIZED_USER",
"BC_AUTH_TT"
],
"type": "string"
},
"instagramAccountId": {
"description": "Meta only. Instagram identity the ad runs AS (creative.instagram_user_id), overriding the account linked to the Page. Live-verified against a Page-post creative.",
"type": "string"
},
"leadGenFormId": {
"description": "Lead Gen form ID to attach to the boosted ad's creative. REQUIRED when `goal` is `lead_generation`; ignored for other goals. Meta: the leadgen_forms ID (create one via POST /apis/v1/ads/lead-forms).",
"type": "string"
},
"lifetimeBudgetCap": {
"description": "X only (400 on another platform or on a lifetime budget). A lifetime total, in whole currency units, that caps a daily budget (budgetType daily). Must be at least budgetAmount.",
"exclusiveMinimum": 0,
"type": "number"
},
"linkUrl": {
"description": "Website URL for non-messaging CTA buttons. Send it with `callToAction`. Omit for messaging boosts. Meta: adds a top-level `call_to_action` to the post-reference creative.",
"format": "uri",
"type": "string"
},
"locationTargetingType": {
"description": "Google only (400 elsewhere). Written on the campaign the boost creates.",
"enum": [
"presence",
"presence_or_interest"
],
"type": "string"
},
"metaObjective": {
"description": "Meta only, with `goal: engagement` and without `adSetId` (400 otherwise).",
"enum": [
"OUTCOME_ENGAGEMENT"
],
"type": "string"
},
"name": {
"maxLength": 255,
"type": "string"
},
"optimizationGoal": {
"description": "Ad-set optimization goal override. Meta, or TikTok with `goal: video_views`. TikTok: ENGAGED_VIEW (6-second Focused View, the default) or ENGAGED_VIEW_FIFTEEN (15-second views), both billed per view (CPV). Any other value is a 400.",
"type": "string"
},
"platformPostId": {
"description": "Platform post ID (alternative to postId). Reddit: the post id, with or without the `t3_` prefix. Meta: a Page post id (`_` or the bare post id) or an Instagram media id.",
"type": "string"
},
"platformSpecificData": {
"description": "Platform-specific options. The platform is derived from `connectionId`; sending options for a different platform returns a 400. LinkedIn (campaign bidding and delivery controls) and Meta (the bid trio) have options today.",
"oneOf": [
{
"additionalProperties": false,
"description": "LinkedIn-specific options for POST /apis/v1/ads/boost and POST /apis/v1/ads/create: campaign bidding and delivery controls, plus the LinkedIn-only creative formats on /apis/v1/ads/create. Unknown keys are rejected.",
"properties": {
"audienceExpansionEnabled": {
"description": "Enable LinkedIn audience expansion. Defaults to false.",
"type": "boolean"
},
"carousel": {
"additionalProperties": false,
"description": "POST /apis/v1/ads/create only. Carousel ad with 2-10 image cards. Mutually exclusive with the other creative sources.",
"properties": {
"cards": {
"items": {
"additionalProperties": false,
"properties": {
"headline": {
"description": "Card title. Falls back to the ad-level headline.",
"type": "string"
},
"imageUrl": {
"format": "uri",
"type": "string"
},
"landingUrl": {
"description": "Per-card click destination. LinkedIn requires one on every card; the ad-level `linkUrl` backfills cards that omit it.",
"format": "uri",
"type": "string"
}
},
"required": [
"imageUrl"
],
"type": "object"
},
"maxItems": 10,
"minItems": 2,
"type": "array"
}
},
"required": [
"cards"
],
"type": "object"
},
"connectedTelevisionOnly": {
"description": "Restrict delivery to Connected TV inventory.",
"type": "boolean"
},
"conversation": {
"additionalProperties": false,
"description": "POST /apis/v1/ads/create only. Conversation Ad: a choose-your-path message tree delivered to the member's LinkedIn inbox. Messages are flat nodes wired by local ids. Each button either opens a url or leads to nextMessageId.",
"properties": {
"body": {
"description": "Optional intro body (HTML allowed).",
"type": "string"
},
"firstMessageId": {
"type": "string"
},
"footer": {
"description": "Terms shown at the bottom of the message.",
"type": "string"
},
"headline": {
"description": "Conversation headline. Defaults to the first message's first line.",
"type": "string"
},
"messages": {
"items": {
"additionalProperties": false,
"properties": {
"buttons": {
"items": {
"additionalProperties": true,
"type": "object"
},
"maxItems": 5,
"minItems": 1,
"type": "array"
},
"id": {
"type": "string"
},
"text": {
"maxLength": 500,
"type": "string"
}
},
"required": [
"id",
"text"
],
"type": "object"
},
"maxItems": 25,
"minItems": 1,
"type": "array"
},
"sender": {
"description": "Person or organization URN. Defaults to the authoring Company Page. The sender must be approved for the ad account first (Campaign Manager > Manage message ad senders) or LinkedIn rejects the create with SINMAIL_SENDER_NOT_APPROVED.",
"type": "string"
},
"subject": {
"description": "InMail subject shown in the inbox.",
"type": "string"
}
},
"required": [
"firstMessageId",
"messages",
"subject"
],
"type": "object"
},
"costType": {
"description": "Campaign cost model (billing event). Defaults to `CPM`. Required when `unitCost` is set so the manual bid applies to an explicit cost model.",
"enum": [
"CPM",
"CPC",
"CPV"
],
"type": "string"
},
"creativeSelection": {
"description": "How LinkedIn rotates creatives within the campaign. Defaults to `OPTIMIZED`.",
"enum": [
"OPTIMIZED",
"ROUND_ROBIN"
],
"type": "string"
},
"document": {
"additionalProperties": false,
"description": "POST /apis/v1/ads/create only. Document ad rendered as an in-feed viewer. PDF, PPT or DOC up to 100MB. Mutually exclusive with the other creative sources.",
"properties": {
"title": {
"description": "Document title.",
"type": "string"
},
"url": {
"format": "uri",
"type": "string"
}
},
"required": [
"title",
"url"
],
"type": "object"
},
"event": {
"additionalProperties": false,
"description": "POST /apis/v1/ads/create only. Promotes an existing LinkedIn Event; no headline needed. Mutually exclusive with the other creative sources.",
"properties": {
"urn": {
"description": "LinkedIn Event URN, urn:li:event:N.",
"pattern": "^urn:li:event:\\d+$",
"type": "string"
}
},
"required": [
"urn"
],
"type": "object"
},
"follower": {
"additionalProperties": false,
"description": "POST /apis/v1/ads/create only. Dynamic Follower Ad promoting the Company Page. Supported goals: engagement, awareness. headline and description take exactly one of preApproved or custom. Mutually exclusive with the other creative sources.",
"properties": {
"callToAction": {
"enum": [
"VISIT_ORGANIZATION_COMPANY_PAGE",
"VISIT_ORGANIZATION_LIFE_PAGE",
"VISIT_ORGANIZATION_JOBS_PAGE",
"VISIT_ORGANIZATION_CAREERS_PAGE"
],
"type": "string"
},
"description": {
"additionalProperties": false,
"properties": {
"custom": {
"description": "Free text, reviewed by LinkedIn.",
"type": "string"
},
"preApproved": {
"description": "LinkedIn preset id, not reviewed. Example GET_LATEST_JOBS_AND_INDUSTRY_NEWS.",
"type": "string"
}
},
"type": "object"
},
"headline": {
"additionalProperties": false,
"properties": {
"custom": {
"description": "Free text, reviewed by LinkedIn.",
"type": "string"
},
"preApproved": {
"description": "LinkedIn preset id, not reviewed. Example GROW_YOUR_BUSINESS_INSIGHTS.",
"type": "string"
}
},
"type": "object"
},
"logoUrl": {
"format": "uri",
"type": "string"
},
"organizationName": {
"type": "string"
},
"showMemberProfilePhoto": {
"description": "Defaults to true.",
"type": "boolean"
}
},
"required": [
"callToAction",
"description",
"headline"
],
"type": "object"
},
"jobs": {
"additionalProperties": false,
"description": "POST /apis/v1/ads/create only. Dynamic Jobs Ad promoting your open roles, personalized with the viewer's profile photo. Mutually exclusive with the other creative sources.",
"properties": {
"buttonLabel": {
"additionalProperties": false,
"properties": {
"custom": {
"description": "Free text, reviewed by LinkedIn.",
"type": "string"
},
"preApproved": {
"description": "LinkedIn preset id, not reviewed. One of SEE_MORE_JOBS, VIEW_MORE, CAREERS_AT_COMPANY.",
"type": "string"
}
},
"type": "object"
},
"headline": {
"additionalProperties": false,
"properties": {
"custom": {
"description": "Free text, reviewed by LinkedIn.",
"type": "string"
},
"preApproved": {
"description": "LinkedIn preset id, not reviewed. Example MEMBER_READY_FOR_YOUR_DREAM_JOB.",
"type": "string"
}
},
"type": "object"
},
"logoUrl": {
"format": "uri",
"type": "string"
},
"organizationName": {
"type": "string"
},
"showMemberProfilePhoto": {
"description": "Defaults to true.",
"type": "boolean"
}
},
"required": [
"buttonLabel",
"headline"
],
"type": "object"
},
"offsiteDeliveryEnabled": {
"description": "Deliver on the LinkedIn Audience Network. Defaults to false.",
"type": "boolean"
},
"optimizationTargetType": {
"description": "Campaign `optimizationTargetType` (e.g. `MAX_CLICK`, `TARGET_COST_PER_CLICK`, `MAX_IMPRESSION`). Forwarded verbatim; LinkedIn validates compatibility with the objective and `costType`. Default when omitted, derived from the objective:",
"type": "string"
},
"spotlight": {
"additionalProperties": false,
"description": "POST /apis/v1/ads/create only. Dynamic Spotlight Ad personalized with the viewer's profile photo. Supported goals: traffic, awareness.",
"properties": {
"backgroundImageUrl": {
"description": "Custom background. Replaces the description and the profile photo.",
"format": "uri",
"type": "string"
},
"callToAction": {
"description": "Button label text.",
"type": "string"
},
"description": {
"description": "Mutually exclusive with backgroundImageUrl.",
"type": "string"
},
"headline": {
"type": "string"
},
"landingUrl": {
"format": "uri",
"type": "string"
},
"logoUrl": {
"format": "uri",
"type": "string"
},
"organizationName": {
"type": "string"
},
"showMemberProfilePhoto": {
"description": "Defaults to true.",
"type": "boolean"
}
},
"required": [
"callToAction",
"headline",
"landingUrl"
],
"type": "object"
},
"textAd": {
"additionalProperties": false,
"description": "POST /apis/v1/ads/create only. Classic right-rail Text Ad. The copy lives here; ad-level body and headline are not used. Mutually exclusive with the other creative sources.",
"properties": {
"description": {
"maxLength": 75,
"type": "string"
},
"headline": {
"maxLength": 25,
"type": "string"
},
"imageUrl": {
"description": "Optional 100x100 image.",
"format": "uri",
"type": "string"
},
"landingUrl": {
"format": "uri",
"type": "string"
}
},
"required": [
"description",
"headline",
"landingUrl"
],
"type": "object"
},
"thoughtLeader": {
"additionalProperties": false,
"description": "POST /apis/v1/ads/create only. Sponsors an existing LinkedIn post (a share or ugcPost authored by your organization's Company Page) as the creative, keeping its commentary, author and engagement.",
"properties": {
"postUrn": {
"description": "LinkedIn share or ugcPost URN: urn:li:share:N or urn:li:ugcPost:N. Get it via \"Copy link to post\" on the target LinkedIn post. The URL contains -share- (share) or -ugcPost- (ugcPost), then the numeric id.",
"pattern": "^urn:li:(share|ugcPost):\\d+$",
"type": "string"
}
},
"required": [
"postUrn"
],
"type": "object"
},
"unitCost": {
"description": "Manual bid in WHOLE account-currency units (e.g. 2.5 = $2.50). Requires `costType`. Omit for LinkedIn's automated (max delivery) bidding. LinkedIn enforces its own per-audience min/max bid bounds.",
"type": "number"
}
},
"type": "object"
},
{
"additionalProperties": false,
"description": "Meta (facebook/instagram) options for platformSpecificData on POST /apis/v1/ads/boost and /apis/v1/ads/create. Unknown keys are rejected, not dropped.",
"properties": {
"adSchedule": {
"description": "Dayparting on the ad set being created (Meta `adset_schedule` with `pacing_type: [\"day_parting\"]`). Change it later with `PUT /apis/v1/ads/ad-sets/{adSetId}`. A 400 with `param: platformSpecificData.adSchedule` when:",
"items": {
"additionalProperties": false,
"properties": {
"dayOfWeek": {
"enum": [
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
],
"type": "string"
},
"endHour": {
"description": "Must be after startHour. 24 is midnight at the end of the day.",
"maximum": 24,
"minimum": 1,
"type": "integer"
},
"startHour": {
"maximum": 23,
"minimum": 0,
"type": "integer"
},
"timezoneType": {
"default": "USER",
"description": "Meta `timezone_type`: USER runs the hours in each viewer's time zone, ADVERTISER in the ad account time zone.",
"enum": [
"USER",
"ADVERTISER"
],
"type": "string"
}
},
"required": [
"dayOfWeek",
"endHour",
"startHour"
],
"type": "object"
},
"maxItems": 168,
"minItems": 1,
"type": "array"
},
"bidAmount": {
"description": "Whole currency units (USD: 5 = $5.00). Required when bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP.",
"type": "number"
},
"bidStrategy": {
"description": "Meta bid strategy. Same enum applies at campaign and ad-set level; ad-set value (when set) overrides campaign-level. Cross-field rules: `LOWEST_COST_WITHOUT_CAP` (default): auto-bid, forbids `bidAmount` and `roasAverageFloor`.",
"enum": [
"LOWEST_COST_WITHOUT_CAP",
"LOWEST_COST_WITH_BID_CAP",
"COST_CAP",
"LOWEST_COST_WITH_MIN_ROAS"
],
"type": "string"
},
"customerLifecycle": {
"additionalProperties": false,
"description": "Meta's Customer Lifecycle Strategy on a Sales ad set (Meta `ad_set_goal`). Rejected with 400 in adSetId attach mode: use PUT /apis/v1/ads/ad-sets/{adSetId} for an ad set that already exists.",
"properties": {
"engagedAudienceIds": {
"description": "Custom audience ids of people who engaged but have not bought. Required with new_customers_excluding_engaged, not allowed with the other strategies. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.",
"items": {
"type": "string"
},
"type": "array"
},
"existingCustomerAudienceIds": {
"description": "Custom audience ids that define your existing customers. Required with both new_customers strategies (Meta answers 400 subcode 1870251 without them); not allowed with all_customers. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.",
"items": {
"type": "string"
},
"type": "array"
},
"strategy": {
"description": "`all_customers` is \"Maximize conversions from all customers\". `new_customers` is \"Acquire new customers\" (excludes existing customers). `new_customers_excluding_engaged` also excludes people who engaged with you but have not bought yet.",
"enum": [
"all_customers",
"new_customers",
"new_customers_excluding_engaged"
],
"type": "string"
}
},
"required": [
"strategy"
],
"type": "object"
},
"dailyMinSpendTarget": {
"description": "Meta daily_min_spend_target on the ad set being created: the least it should spend per day, in whole currency units. A target, not a guarantee.",
"type": "number"
},
"lifetimeMinSpendTarget": {
"description": "Meta lifetime_min_spend_target: the lifetime-budget flavour of dailyMinSpendTarget, in whole currency units. Same rules and same rejections.",
"type": "number"
},
"roasAverageFloor": {
"description": "Decimal ROAS multiplier (2.0 = 2.0x). Required when bidStrategy is LOWEST_COST_WITH_MIN_ROAS; sending it without bidStrategy is a 400.",
"type": "number"
}
},
"type": "object"
}
]
},
"postId": {
"type": "string"
},
"promoCodes": {
"description": "TikTok Smart+ Web Conversions only (requires `smartPlus: true`, goal `conversions`). Promo codes or offers TikTok highlights on the ad (Ads Manager's \"Add promo code or offer\"). A promo code needs shoppers to enter it at checkout.",
"items": {
"properties": {
"discountCurrency": {
"description": "ISO 4217; required for CASH.",
"type": "string"
},
"discountType": {
"enum": [
"PERCENTAGE",
"CASH"
],
"type": "string"
},
"discountValue": {
"description": "PERCENTAGE: integer 1-100. CASH: amount greater than 0 in discountCurrency.",
"type": "number"
},
"minimumPurchaseCurrency": {
"description": "ISO 4217; required for SUBTOTAL.",
"type": "string"
},
"minimumPurchaseType": {
"enum": [
"QUANTITY",
"SUBTOTAL"
],
"type": "string"
},
"minimumPurchaseValue": {
"description": "Required with minimumPurchaseType; QUANTITY is an integer >= 0, SUBTOTAL an amount > 0.",
"type": "number"
},
"promoCode": {
"description": "Code entered at checkout; omit for an automatic offer.",
"maxLength": 30,
"type": "string"
}
},
"required": [
"discountType",
"discountValue"
],
"type": "object"
},
"maxItems": 10,
"minItems": 1,
"type": "array"
},
"promotedObject": {
"description": "Meta, TikTok and Reddit. What the conversion ad set optimizes toward, so a boost of an existing organic post can run for a conversion instead of only engagement or traffic.",
"properties": {
"customConversionId": {
"description": "Meta only. Custom Conversion to optimize against, instead of pixelId + customEventType.",
"type": "string"
},
"customEventStr": {
"description": "Meta only. Pixel custom event name as it appears in Events Manager; requires customEventType OTHER.",
"type": "string"
},
"customEventType": {
"description": "Meta: standard pixel event (PURCHASE, LEAD, ...) or OTHER with customEventStr. TikTok: optimization_event code (e.g.",
"type": "string"
},
"pixelId": {
"description": "Meta Pixel id, TikTok Pixel (numeric id or the alphanumeric pixel code from Events Manager, resolved for you), or Reddit pixel id.",
"type": "string"
}
},
"type": "object"
},
"rawTargeting": {
"additionalProperties": true,
"description": "Meta only. A Meta-native targeting spec (e.g. `{ \"geo_locations\": { \"cities\": [{ \"key\": \"...\", \"radius\": 15, \"distance_unit\": \"kilometer\" }] } }`). Sent alone, it is forwarded unchanged.",
"type": "object"
},
"regionalRegulatedCategories": {
"description": "Meta only. Regional regulation categories required when the ad set targets certain countries (e.g.",
"items": {
"type": "string"
},
"type": "array"
},
"regionalRegulationIdentities": {
"additionalProperties": {
"type": [
"string",
"integer"
]
},
"description": "Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set.",
"type": "object"
},
"rehostOnInstagramVideoRejection": {
"default": true,
"description": "Meta only (a 400 elsewhere). Controls the fallback when Meta refuses an existing Instagram video as the ad (subcode 1815279).",
"type": "boolean"
},
"roasAverageFloor": {
"description": "Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400.",
"type": "number"
},
"schedule": {
"description": "Alias of the top-level `startDate` / `endDate`, kept for existing callers. Sending both forms with differing values is a 400.",
"properties": {
"endDate": {
"description": "Alias of endDate, kept for existing callers",
"format": "date-time",
"type": "string"
},
"startDate": {
"description": "Alias of startDate, kept for existing callers",
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"smartPlus": {
"description": "TikTok only. Run the Spark post in a Smart+ campaign instead of a regular one: goal `conversions` = Smart+ Web Conversions, `lead_generation` = Smart+ Lead Generation. Rejected with a 400 on other platforms. Requires:",
"type": "boolean"
},
"smartTargeting": {
"description": "TikTok only (a 400 elsewhere). TikTok Smart Targeting on the ad group: `audience` is TikTok's `smart_audience_enabled`, `interestsBehaviors` its `smart_interest_behavior_enabled`.",
"properties": {
"audience": {
"description": "TikTok smart_audience_enabled.",
"type": "boolean"
},
"interestsBehaviors": {
"description": "TikTok smart_interest_behavior_enabled.",
"type": "boolean"
}
},
"type": "object"
},
"sparkAuthCode": {
"description": "TikTok-only. Spark Code (the creator's `auth_code`) authorizing cross-creator Spark Ads: the advertiser can boost a video owned by a DIFFERENT TikTok account. Maps to `auth_code` on the creative entry of /v2/ad/create/.",
"type": "string"
},
"sparkPosts": {
"description": "TikTok Smart+ only (requires `smartPlus: true`; a 400 on other platforms). Several Spark posts as creatives of ONE Smart+ ad, each with its own post code. Replaces `platformPostId` + `sparkAuthCode`.",
"items": {
"properties": {
"platformPostId": {
"description": "TikTok post (item) id.",
"type": "string"
},
"sparkAuthCode": {
"description": "That post's Spark code.",
"type": "string"
}
},
"required": [
"platformPostId",
"sparkAuthCode"
],
"type": "object"
},
"maxItems": 50,
"minItems": 1,
"type": "array"
},
"specialAdCategories": {
"description": "Meta only. Required for housing, employment, credit, or political ads.",
"items": {
"enum": [
"HOUSING",
"EMPLOYMENT",
"CREDIT",
"FINANCIAL_PRODUCTS_SERVICES",
"ISSUES_ELECTIONS_POLITICS",
"ONLINE_GAMBLING_AND_GAMING"
],
"type": "string"
},
"type": "array"
},
"specialAdCategoryCountry": {
"description": "Meta (metaads) only. 2-letter ISO country codes the special ad category applies to. Requires specialAdCategories to be set (400 otherwise).",
"items": {
"type": "string"
},
"type": "array"
},
"startDate": {
"description": "Ad-set start time (ISO 8601, e.g. \"2026-06-10T09:00:00Z\"), mapped to the ad set's `start_time`. When omitted the ad starts delivering immediately.",
"format": "date-time",
"type": "string"
},
"status": {
"description": "Publish state of the created entities, on every platform. Omitted or ACTIVE publishes live (default). PAUSED pauses only the top-most object this boost creates and switches everything below it on:",
"enum": [
"ACTIVE",
"PAUSED"
],
"type": "string"
},
"targeting": {
"description": "Same geo/demographic fields as the `TargetingSpec` used by /apis/v1/ads/create. Geo keys (`regions`/`cities`/`zips`/`metros`) resolve via GET /apis/v1/ads/targeting/search?dimension=geo. Meta only: city radius and lat/lng `customLocations`.",
"properties": {
"advantage_audience": {
"description": "Meta only. 0 = disabled (default), 1 = enabled.",
"enum": [
0,
1
],
"type": "integer"
},
"ageMax": {
"maximum": 65,
"minimum": 13,
"type": "integer"
},
"ageMin": {
"maximum": 65,
"minimum": 13,
"type": "integer"
},
"cities": {
"description": "City targeting. Optional `radius` + `distanceUnit` extend beyond the city limits (both set together, Meta only).",
"items": {
"properties": {
"distanceUnit": {
"enum": [
"mile",
"kilometer"
],
"type": "string"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"radius": {
"description": "Requires distanceUnit. Meta enforces a minimum city radius (~17 km / 10 mi); smaller values resolve to a 0-size audience and the ad fails at launch. For a tighter catchment use customLocations (lat/lng).",
"type": "number"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
},
"countries": {
"description": "ISO country codes. Required for TikTok boosts (TikTok's ad group requires location_ids); optional on other platforms.",
"items": {
"type": "string"
},
"type": "array"
},
"customLocations": {
"description": "Point-radius (lat/lng) targeting (Meta custom_locations). No geo `key` lookup needed.",
"items": {
"properties": {
"address": {
"description": "Optional label, sent to Meta as `address_string`.",
"type": "string"
},
"distanceUnit": {
"enum": [
"mile",
"kilometer"
],
"type": "string"
},
"latitude": {
"maximum": 90,
"minimum": -90,
"type": "number"
},
"longitude": {
"maximum": 180,
"minimum": -180,
"type": "number"
},
"name": {
"type": "string"
},
"radius": {
"type": "number"
}
},
"required": [
"distanceUnit",
"latitude",
"longitude",
"radius"
],
"type": "object"
},
"type": "array"
},
"gender": {
"description": "Applied on Meta, TikTok, Pinterest and Reddit. Ignored on Google, LinkedIn and X.",
"enum": [
"all",
"male",
"female"
],
"type": "string"
},
"interests": {
"description": "Interest objects from /apis/v1/ads/interests. Each must include id and name.",
"items": {
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"type": "object"
},
"type": "array"
},
"languages": {
"description": "Meta locale ids (numeric), passed through as given. Reddit: language codes (e.g. `en`).",
"items": {
"type": "string"
},
"type": "array"
},
"metros": {
"description": "DMA / metro-area targeting. `key` is the platform's metro ID (e.g. Meta `DMA:807`).",
"items": {
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
},
"regions": {
"description": "Region/state targeting. `key` from /apis/v1/ads/targeting/search?dimension=geo&geoType=region.",
"items": {
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
},
"zips": {
"description": "Postal/ZIP targeting. `key` is the platform's postal location ID (e.g. Meta `US:94304`).",
"items": {
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"tracking": {
"description": "Meta only, except `pixelId`, which also picks the Reddit pixel of the new ad group (`promotedObject.pixelId` wins when both are sent). Tracking specs (pixel, URL tags).",
"properties": {
"pixelId": {
"type": "string"
},
"urlTags": {
"description": "URL parameters appended to the ad link, rendered as `key=value` pairs joined with `&`.",
"items": {
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"validateOnly": {
"default": false,
"description": "Meta only (facebook, instagram and Meta ads connections). Returns 200 with the same body as a validateOnly POST /apis/v1/ads/create (`validateOnly`, `results` per node, `message`).",
"type": "boolean"
},
"whatsappPhoneNumber": {
"description": "Meta WhatsApp only. E.164 number already paired with the Page. Omit to use the default pairing. Requires WHATSAPP_MESSAGE callToAction. Stored as creative.whatsappPhoneNumber on the ad.",
"pattern": "^\\+[1-9]\\d{6,14}$",
"type": "string"
},
"workflowId": {
"description": "Meta messaging boosts only (callToAction MESSAGE_PAGE, WHATSAPP_MESSAGE or INSTAGRAM_MESSAGE). A workflow in the account's profile, started in the conversation a click on the ad opens. Stored on the ad.",
"pattern": "^[a-fA-F0-9]{24}$",
"type": "string"
}
},
"required": [
"adAccountId",
"goal",
"name"
],
"type": "object"
}
}
},
"required": true
},
"x-aisa-status": "enabled",
"x-aisa-pricing": {
"description": "Ads operations are free. Ad spend is billed by the ad platform to the connected ad account, never by AIsa.",
"kind": "no_customer_charge"
},
"components": {
"securitySchemes": {
"bearerAuth": {
"scheme": "bearer",
"type": "http"
}
}
}
}
Cost and request rules
A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Required with the value "spend" when the request can spend money or change spend. Without it the request is refused with 409 confirmation_required, which describes what would happen; nothing is sent to the ad platform.
Available options:
spend Passed to the ad platform integration: a retry with the same key returns the first result instead of acting twice. AIsa never retries a write for you.
Required string length:
1 - 191Query Parameters
The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.
Pattern:
^adc_[0-9A-Za-z]+$Body
application/json
Platform ad account ID
Available goals vary by platform. Meta (Facebook/Instagram) and TikTok support all 7. LinkedIn supports all except app_promotion. X supports engagement, traffic, awareness, video_views, app_promotion.
Available options:
engagement, traffic, awareness, video_views, lead_generation, conversions, app_promotion Maximum string length:
255Meta, or TikTok with smartPlus: true. Attach the boosted post to this existing ad set instead of creating a campaign. Meta: the ad set then owns budget, schedule and targeting; sending those too is a 400. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.
Exact name for the ad-group level this boost provisions. Omitted keeps the default - Ad Group. Meta: ad set; TikTok, Pinterest, Google: ad group; X: line item; LinkedIn: the campaign under the campaign group.
Maximum string length:
255Every platform, same semantics as POST /apis/v1/ads/create. Sets the switch of the new ad set alone and overrides status for it. Omitted, it follows status.
Available options:
ACTIVE, PAUSED Request-side publish switch for adStatus on ad creation endpoints only (status, campaignStatus and adSetStatus carry their own inline ACTIVE/PAUSED enum there; the status-update endpoints are a separate lowercase active/paused…
Available options:
ACTIVE, PAUSED Meta only. Ad-set attribution windows, same shape as POST /apis/v1/ads/create.
Required array length:
1 - 3 elementsShow child attributes
Show child attributes
Deprecated: send it inside platformSpecificData instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400.
Deprecated: send it inside platformSpecificData instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400.
Available options:
LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS Meta only. Extra primary-text options Meta rotates on the boosted post (asset_feed_spec.bodies with DEGREES_OF_FREEDOM). The post keeps its own text as one of the options. Works for Facebook posts and Instagram media.
Required array length:
1 - 5 elementsAlias of budgetAmount + budgetType, kept for existing callers
Show child attributes
Show child attributes
Budget in whole currency units, the same flat field as POST /apis/v1/ads/create. Required unless adSetId is set. Minimum varies: TikTok=$20, Pinterest=$5, others=$1
Meta only, same semantics as POST /apis/v1/ads/create: campaign = Advantage campaign budget (CBO), the budget and bid strategy sit on the campaign and the ad set inherits them. Default adset. Not allowed with adSetId.
Available options:
adset, campaign Goes together with budgetAmount. lifetime requires schedule.endDate.
Available options:
daily, lifetime CTA button label. Non-messaging CTAs require linkUrl. WHATSAPP_MESSAGE, MESSAGE_PAGE, and INSTAGRAM_MESSAGE do not require a URL and reject linkUrl.
Exact name for the campaign this boost provisions. Omitted keeps the default - Campaign. Every platform: on LinkedIn it names the campaign group. Ignored on the Meta attach shape (adSetId), which creates no campaign.
Maximum string length:
255Every platform, same semantics as POST /apis/v1/ads/create. Sets the switch of the new campaign alone (LinkedIn: the campaign group) and overrides status for it. When omitted, it follows status.
Available options:
ACTIVE, PAUSED The ads connection (adc_...), when not sent as the connectionId query parameter.
Pattern:
^adc_[0-9A-Za-z]+$Meta Advantage+ creative enhancements. Map snake_case feature names to OPT_IN or OPT_OUT; Meta validates supported keys and unspecified features default to OPT_OUT.
Show child attributes
Show child attributes
ISO 4217 currency code matching the ad account's currency. Meta only.
Required string length:
3Meta only. Ad-set destination_type: where the click LANDS, as opposed to instagramAccountId which is who the ad runs as. Independent of plain link CTAs and their goal.
Available options:
INSTAGRAM_PROFILE, WEBSITE, ON_AD, MESSENGER, WHATSAPP, INSTAGRAM_DIRECT Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26).
Maximum string length:
100Legal entity that pays for the ad. Can differ from dsaBeneficiary (for example, an agency paying for a client's ads). Same rules as dsaBeneficiary: required for EU targeting unless the ad account has a default payor.
Maximum string length:
100Ad-set end time (ISO 8601). Required for lifetime budgets. Same field as on POST /apis/v1/ads/create. Maps to the ad set's end_time (on X, the line item's end_time; X campaigns carry no flight dates).
TikTok only. Create the ad group and the Spark ad under this existing TikTok campaign instead of creating a new campaign. The campaign keeps its own status and objective (the objective must fit goal). Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.
TikTok only. The identity the ad runs as (the profile shown on the ad), from GET /apis/v1/ads/tiktok-identities. Default: the connected TikTok account's own identity.
TikTok only. Type of identityId; resolved from the advertiser's identity list when omitted.
Available options:
TT_USER, CUSTOMIZED_USER, BC_AUTH_TT Meta only. Instagram identity the ad runs AS (creative.instagram_user_id), overriding the account linked to the Page. Live-verified against a Page-post creative.
Lead Gen form ID to attach to the boosted ad's creative. REQUIRED when goal is lead_generation; ignored for other goals. Meta: the leadgen_forms ID (create one via POST /apis/v1/ads/lead-forms).
X only (400 on another platform or on a lifetime budget). A lifetime total, in whole currency units, that caps a daily budget (budgetType daily). Must be at least budgetAmount.
Website URL for non-messaging CTA buttons. Send it with callToAction. Omit for messaging boosts. Meta: adds a top-level call_to_action to the post-reference creative.
Google only (400 elsewhere). Written on the campaign the boost creates.
Available options:
presence, presence_or_interest Meta only, with goal: engagement and without adSetId (400 otherwise).
Available options:
OUTCOME_ENGAGEMENT Ad-set optimization goal override. Meta, or TikTok with goal: video_views. TikTok: ENGAGED_VIEW (6-second Focused View, the default) or ENGAGED_VIEW_FIFTEEN (15-second views), both billed per view (CPV). Any other value is a 400.
Platform post ID (alternative to postId). Reddit: the post id, with or without the t3_ prefix. Meta: a Page post id (_ or the bare post id) or an Instagram media id.
Platform-specific options. The platform is derived from connectionId; sending options for a different platform returns a 400. LinkedIn (campaign bidding and delivery controls) and Meta (the bid trio) have options today.
- Option 1
- Option 2
Show child attributes
Show child attributes
TikTok Smart+ Web Conversions only (requires smartPlus: true, goal conversions). Promo codes or offers TikTok highlights on the ad (Ads Manager's "Add promo code or offer"). A promo code needs shoppers to enter it at checkout.
Required array length:
1 - 10 elementsShow child attributes
Show child attributes
Meta, TikTok and Reddit. What the conversion ad set optimizes toward, so a boost of an existing organic post can run for a conversion instead of only engagement or traffic.
Show child attributes
Show child attributes
Meta only. A Meta-native targeting spec (e.g. { "geo_locations": { "cities": [{ "key": "...", "radius": 15, "distance_unit": "kilometer" }] } }). Sent alone, it is forwarded unchanged.
Meta only. Regional regulation categories required when the ad set targets certain countries (e.g.
Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set.
Show child attributes
Show child attributes
Meta only (a 400 elsewhere). Controls the fallback when Meta refuses an existing Instagram video as the ad (subcode 1815279).
Deprecated: send it inside platformSpecificData instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400.
Alias of the top-level startDate / endDate, kept for existing callers. Sending both forms with differing values is a 400.
Show child attributes
Show child attributes
TikTok only. Run the Spark post in a Smart+ campaign instead of a regular one: goal conversions = Smart+ Web Conversions, lead_generation = Smart+ Lead Generation. Rejected with a 400 on other platforms. Requires:
TikTok only (a 400 elsewhere). TikTok Smart Targeting on the ad group: audience is TikTok's smart_audience_enabled, interestsBehaviors its smart_interest_behavior_enabled.
Show child attributes
Show child attributes
TikTok-only. Spark Code (the creator's auth_code) authorizing cross-creator Spark Ads: the advertiser can boost a video owned by a DIFFERENT TikTok account. Maps to auth_code on the creative entry of /v2/ad/create/.
TikTok Smart+ only (requires smartPlus: true; a 400 on other platforms). Several Spark posts as creatives of ONE Smart+ ad, each with its own post code. Replaces platformPostId + sparkAuthCode.
Required array length:
1 - 50 elementsShow child attributes
Show child attributes
Meta only. Required for housing, employment, credit, or political ads.
Available options:
HOUSING, EMPLOYMENT, CREDIT, FINANCIAL_PRODUCTS_SERVICES, ISSUES_ELECTIONS_POLITICS, ONLINE_GAMBLING_AND_GAMING Meta (metaads) only. 2-letter ISO country codes the special ad category applies to. Requires specialAdCategories to be set (400 otherwise).
Ad-set start time (ISO 8601, e.g. "2026-06-10T09:00:00Z"), mapped to the ad set's start_time. When omitted the ad starts delivering immediately.
Publish state of the created entities, on every platform. Omitted or ACTIVE publishes live (default). PAUSED pauses only the top-most object this boost creates and switches everything below it on:
Available options:
ACTIVE, PAUSED Same geo/demographic fields as the TargetingSpec used by /apis/v1/ads/create. Geo keys (regions/cities/zips/metros) resolve via GET /apis/v1/ads/targeting/search?dimension=geo. Meta only: city radius and lat/lng customLocations.
Show child attributes
Show child attributes
Meta only, except pixelId, which also picks the Reddit pixel of the new ad group (promotedObject.pixelId wins when both are sent). Tracking specs (pixel, URL tags).
Show child attributes
Show child attributes
Meta only (facebook, instagram and Meta ads connections). Returns 200 with the same body as a validateOnly POST /apis/v1/ads/create (validateOnly, results per node, message).
Meta WhatsApp only. E.164 number already paired with the Page. Omit to use the default pairing. Requires WHATSAPP_MESSAGE callToAction. Stored as creative.whatsappPhoneNumber on the ad.
Pattern:
^\+[1-9]\d{6,14}$Meta messaging boosts only (callToAction MESSAGE_PAGE, WHATSAPP_MESSAGE or INSTAGRAM_MESSAGE). A workflow in the account's profile, started in the conversation a click on the ad opens. Stored on the ad.
Pattern:
^[a-fA-F0-9]{24}$