Create messaging ad
curl --request POST \
--url https://api.aisa.one/apis/v1/ads/messaging \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"adAccountId": "act_757082720485182",
"name": "WhatsApp existing post"
}
'import requests
url = "https://api.aisa.one/apis/v1/ads/messaging"
payload = {
"adAccountId": "act_757082720485182",
"name": "WhatsApp existing post"
}
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', name: 'WhatsApp existing post'})
};
fetch('https://api.aisa.one/apis/v1/ads/messaging', 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/messaging",
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',
'name' => 'WhatsApp existing post'
]),
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/messaging"
payload := strings.NewReader("{\n \"adAccountId\": \"act_757082720485182\",\n \"name\": \"WhatsApp existing post\"\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/messaging")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"adAccountId\": \"act_757082720485182\",\n \"name\": \"WhatsApp existing post\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.aisa.one/apis/v1/ads/messaging")
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 \"name\": \"WhatsApp existing post\"\n}"
response = http.request(request)
puts response.read_body{
"message": "<string>",
"results": [
{
"node": "campaign",
"status": "validated",
"reason": "<string>"
}
],
"validateOnly": true
}{
"ad": {},
"adType": "single",
"message": "<string>",
"warnings": [
"<string>"
]
}{
"error": {
"code": "<string>",
"details": {},
"message": "<string>",
"param": "<string>",
"retryHint": "<string>",
"retryable": true,
"type": "<string>"
}
}AIsa Ads
Create messaging ad
Messaging Ads. 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. Creates a messaging ad that spends the given budget. validateOnly=true checks the request without acting and needs no confirmation. Creates a Meta ad that opens a chat with you on WhatsApp, Messenger or Instagram Direct when someone taps it. ### Destinations `destination` selects where the tapped ad opens a conversation: WhatsApp the Page's Messenger inbox the linked Instagram account's Direct inbox `destinations` puts two or three of them on one ad set and lets Meta pick the app per viewer.
<!-- 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
/
messaging
Create messaging ad
curl --request POST \
--url https://api.aisa.one/apis/v1/ads/messaging \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"adAccountId": "act_757082720485182",
"name": "WhatsApp existing post"
}
'import requests
url = "https://api.aisa.one/apis/v1/ads/messaging"
payload = {
"adAccountId": "act_757082720485182",
"name": "WhatsApp existing post"
}
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', name: 'WhatsApp existing post'})
};
fetch('https://api.aisa.one/apis/v1/ads/messaging', 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/messaging",
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',
'name' => 'WhatsApp existing post'
]),
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/messaging"
payload := strings.NewReader("{\n \"adAccountId\": \"act_757082720485182\",\n \"name\": \"WhatsApp existing post\"\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/messaging")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"adAccountId\": \"act_757082720485182\",\n \"name\": \"WhatsApp existing post\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.aisa.one/apis/v1/ads/messaging")
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 \"name\": \"WhatsApp existing post\"\n}"
response = http.request(request)
puts response.read_body{
"message": "<string>",
"results": [
{
"node": "campaign",
"status": "validated",
"reason": "<string>"
}
],
"validateOnly": true
}{
"ad": {},
"adType": "single",
"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/messaging
- Availability: enabled
- Request URL template:
https://api.aisa.one/apis/v1/ads/messaging - connectionId: query; required
- X-Aisa-Confirm: header; optional
- Idempotency-Key: header; optional
- Runtime facts: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09
{
"operationId": "post_aisa_ads_apis_v1_ads_messaging",
"method": "POST",
"path": "/apis/v1/ads/messaging",
"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",
"budgetAmount": 2.61,
"budgetType": "daily",
"connectionId": "adc_7f3k2m9q",
"creatives": [
{
"objectStoryId": "811889972008357_123456789"
}
],
"destination": "whatsapp",
"name": "WhatsApp existing post",
"status": "PAUSED"
},
"schema": {
"additionalProperties": true,
"description": "Besides the `required` list, the request must use EXACTLY ONE of these shapes: Single-creative: `headline`, `body`, and one of `imageUrl` / `video`, OR `platformPostId` / `objectStoryId` to reuse an organic post.",
"properties": {
"adAccountId": {
"description": "Meta ad account ID, e.g. `act_123456789`.",
"minLength": 1,
"type": "string"
},
"adSetId": {
"description": "Attaches the creatives to this EXISTING messaging ad set instead of building a campaign, so the ad set keeps its learning phase. Its `destination_type` must match the ad's destination. 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 set this request provisions. Omitted keeps ` - Ad Set`. Ignored with `adSetId`.",
"maxLength": 255,
"type": "string"
},
"adSetStatus": {
"description": "Ad-set-level status, same semantics as `POST /apis/v1/ads/create`. Sets the new ad set's switch alone and overrides `status` for it.",
"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"
},
"advantageAudience": {
"description": "Meta's Advantage+ audience expansion. `0` (default) keeps targeting strict; `1` lets Meta expand beyond the supplied targeting when its delivery system finds better matches. Always sent on CREATE (Meta requires it).",
"enum": [
0,
1
],
"type": "integer"
},
"ageMax": {
"maximum": 65,
"minimum": 13,
"type": "integer"
},
"ageMin": {
"maximum": 65,
"minimum": 13,
"type": "integer"
},
"audienceExclude": {
"description": "Custom or lookalike audience ids to exclude. 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"
},
"minItems": 1,
"type": "array"
},
"audienceId": {
"description": "Custom audience ID to target. 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"
},
"audienceInclude": {
"description": "Custom or lookalike audience ids to include. 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"
},
"minItems": 1,
"type": "array"
},
"behaviors": {
"description": "Behavior ids from /apis/v1/ads/targeting/search?dimension=behavior. Meta: each dimension is its own flexible_spec entry (OR within, AND across). TikTok: video/creator interaction categories, sent as the ad group's actions.",
"items": {
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"type": "array"
},
"bidAmount": {
"description": "Whole currency units (e.g. `5` = $5.00 on a USD account). Required when `bidStrategy` is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`; rejected otherwise.",
"exclusiveMinimum": 0,
"type": "number"
},
"bidStrategy": {
"description": "Meta bid strategy applied to the shared ad set. Defaults to `LOWEST_COST_WITHOUT_CAP` (auto-bid) when omitted. `LOWEST_COST_WITH_BID_CAP` and `COST_CAP` require `bidAmount`. `LOWEST_COST_WITH_MIN_ROAS` requires `roasAverageFloor`.",
"enum": [
"LOWEST_COST_WITHOUT_CAP",
"LOWEST_COST_WITH_BID_CAP",
"COST_CAP",
"LOWEST_COST_WITH_MIN_ROAS"
],
"type": "string"
},
"body": {
"description": "Primary text shown above the image / video. Single-creative shape only. Mutually exclusive with `creatives[]`.",
"minLength": 1,
"type": "string"
},
"budgetAmount": {
"description": "Budget amount in the ad account's currency major units (e.g. dollars for USD, not cents). Must be > 0. Required unless `adSetId` is set (the ad set owns it) or `existingCampaignId` names a campaign with a campaign budget.",
"exclusiveMinimum": 0,
"type": "number"
},
"budgetLevel": {
"description": "Where the budget lives. `adset` (default) puts it on the new ad set. `campaign` creates an Advantage campaign budget (CBO): the budget and bid strategy sit on the campaign and the ad set inherits them, same as POST /apis/v1/ads/create.",
"enum": [
"adset",
"campaign"
],
"type": "string"
},
"budgetType": {
"description": "Required unless `adSetId` is set or `existingCampaignId` names a campaign with a campaign budget. `lifetime` requires `endDate`.",
"enum": [
"daily",
"lifetime"
],
"type": "string"
},
"campaignName": {
"description": "Exact name for the campaign this request provisions. Omitted keeps ` - Campaign`. Ignored with `adSetId` (the ad set already has a campaign).",
"maxLength": 255,
"type": "string"
},
"campaignStatus": {
"description": "Campaign-level status, same semantics as `POST /apis/v1/ads/create`. Defaults to `status`. `PAUSED`: holds the new campaign off while the ad set and ads switch on (one resume call brings the whole hierarchy live).",
"enum": [
"ACTIVE",
"PAUSED"
],
"type": "string"
},
"carouselCards": {
"description": "Messaging and CTWA only (a 400 on POST /apis/v1/ads/call). A hand-built carousel of 2-10 image cards, sent to Meta in the given order as `link_data.child_attachments`.",
"items": {
"description": "One card of a messaging ad carousel (Meta link_data.child_attachments). Every card opens the same conversation, so a card has no link of its own.",
"properties": {
"callToAction": {
"description": "Optional. Must equal the destination's messaging call to action (WHATSAPP_MESSAGE for whatsapp, MESSAGE_PAGE for messenger, INSTAGRAM_MESSAGE for instagram_direct; with `destinations` the first one listed).",
"type": "string"
},
"description": {
"description": "Card description, under the title.",
"maxLength": 255,
"type": "string"
},
"headline": {
"description": "Card title (Meta name).",
"maxLength": 255,
"type": "string"
},
"imageUrl": {
"description": "Card image. Uploaded to the ad account and sent as the card image_hash (by URL on validateOnly).",
"format": "uri",
"type": "string"
},
"linkUrl": {
"description": "Not accepted: a 400. The card tap opens the conversation, not a website.",
"type": "string"
}
},
"required": [
"imageUrl"
],
"type": "object"
},
"maxItems": 10,
"minItems": 2,
"type": "array"
},
"cities": {
"description": "City-level geo targeting for local CTWA campaigns. Each entry maps to Meta's TargetingGeoLocationCity; `key` is Meta's city ID. `radius` and `distance_unit` are coupled: set both or neither.",
"items": {
"properties": {
"distance_unit": {
"enum": [
"mile",
"kilometer"
],
"type": "string"
},
"key": {
"minLength": 1,
"type": "string"
},
"radius": {
"exclusiveMinimum": 0,
"type": "number"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
},
"connectionId": {
"description": "The ads connection (adc_...), when not sent as the connectionId query parameter.",
"pattern": "^adc_[0-9A-Za-z]+$",
"type": "string"
},
"countries": {
"description": "ISO 3166-1 alpha-2 country codes. Defaults to `[\"US\"]` only when no other geo (`cities`, `regions`, `zips`, `metros`, `customLocations`) is supplied.",
"items": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"type": "array"
},
"countryGroups": {
"description": "Meta only. Continents and trade blocs (`geo_locations.country_groups`), for targeting a whole region without listing its countries. Combines with `countries` rather than replacing it, and is also accepted under `excludedLocations`.",
"items": {
"enum": [
"africa",
"asia",
"europe",
"north_america",
"south_america",
"oceania",
"central_america",
"caribbean",
"eea",
"euro_area",
"nafta",
"mercosur",
"afta",
"apec",
"gcc",
"cisfta",
"emerging_markets",
"itunes_app_store",
"android_free_store",
"android_paid_store"
],
"type": "string"
},
"type": "array"
},
"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"
},
"creatives": {
"description": "Multi-creative shape: N CTWA ads under one campaign + one ad set, sharing budget and targeting. Fresh and existing creatives can be mixed. Each entry supplies headline, body, and image/video, or a platformPostId or objectStoryId reference.",
"items": {
"description": "Supply headline, body, and image/video; or body and carouselCards (no headline); or exactly one existing post reference. References cannot be combined with headline, body, imageUrl, video or carouselCards; welcomeMessage works on all three.",
"properties": {
"body": {
"description": "Primary text shown above the image / video.",
"minLength": 1,
"type": "string"
},
"carouselCards": {
"description": "A 2-10 card carousel for this entry instead of `imageUrl` / `video`; `body` is required. Same rules as the top-level `carouselCards`. Carousel and single-media entries can be mixed on one ad set.",
"items": {
"description": "One card of a messaging ad carousel (Meta link_data.child_attachments). Every card opens the same conversation, so a card has no link of its own.",
"properties": {
"callToAction": {
"description": "Optional. Must equal the destination's messaging call to action (WHATSAPP_MESSAGE for whatsapp, MESSAGE_PAGE for messenger, INSTAGRAM_MESSAGE for instagram_direct; with `destinations` the first one listed).",
"type": "string"
},
"description": {
"description": "Card description, under the title.",
"maxLength": 255,
"type": "string"
},
"headline": {
"description": "Card title (Meta name).",
"maxLength": 255,
"type": "string"
},
"imageUrl": {
"description": "Card image. Uploaded to the ad account and sent as the card image_hash (by URL on validateOnly).",
"format": "uri",
"type": "string"
},
"linkUrl": {
"description": "Not accepted: a 400. The card tap opens the conversation, not a website.",
"type": "string"
}
},
"required": [
"imageUrl"
],
"type": "object"
},
"maxItems": 10,
"minItems": 2,
"type": "array"
},
"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"
},
"existingPostId": {
"description": "Alias of platformPostId, kept for existing callers. Sending both with different values is a 400.",
"minLength": 1,
"type": "string"
},
"headline": {
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"imageUrl": {
"description": "Image asset. Mutually exclusive with this entry's `video`. Required if neither `video` nor an existing post reference is supplied.",
"format": "uri",
"type": "string"
},
"objectStoryId": {
"description": "Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with platformPostId and fresh creative fields.",
"pattern": "^\\d+_\\d+$",
"type": "string"
},
"platformPostId": {
"description": "Messaging and CTWA only. Platform post or reel ID, the same input boostPost takes as platformPostId. Mutually exclusive with objectStoryId and fresh creative fields. Facebook IDs become object_story_id.",
"minLength": 1,
"type": "string"
},
"video": {
"description": "Video creative. Mutually exclusive with this entry's `imageUrl`. Required if neither `imageUrl` nor an existing post reference is supplied.",
"properties": {
"id": {
"description": "Reuse a video already uploaded to this ad account (list them with GET /apis/v1/ads/videos) instead of re-uploading. Wins over `url`. Provide either `url` or `id`.",
"type": "string"
},
"thumbnailUrl": {
"description": "OPTIONAL: when omitted, the poster is auto-generated from Meta's own preferred video thumbnail. When Meta produces no candidate the request fails with a 502 platform_error (reason: video_thumbnail_unavailable).",
"format": "uri",
"type": "string"
},
"url": {
"description": "Public URL of the video to upload. Provide either `url` or `id`.",
"format": "uri",
"type": "string"
}
},
"type": "object"
},
"welcomeMessage": {
"description": "Custom chat welcome message for this entry: `text` plus exactly one of `prefillText` or `quickReplies` (400 otherwise). Same shape as the top-level `welcomeMessage` of the single-creative shape.",
"properties": {
"prefillText": {
"description": "Message put into the user's text input, ready to send. Replaces Meta's default. Exactly one of prefillText or quickReplies.",
"minLength": 1,
"type": "string"
},
"quickReplies": {
"description": "Tappable chips under the greeting instead of a prefilled message. Exactly one of prefillText or quickReplies.",
"items": {
"properties": {
"payload": {
"maxLength": 1000,
"minLength": 1,
"type": "string"
},
"title": {
"description": "Chip label the person taps.",
"maxLength": 20,
"minLength": 1,
"type": "string"
}
},
"required": [
"payload",
"title"
],
"type": "object"
},
"maxItems": 13,
"minItems": 1,
"type": "array"
},
"text": {
"description": "Greeting shown when the chat opens. Replaces Meta's default.",
"minLength": 1,
"type": "string"
}
},
"required": [
"text"
],
"type": "object"
}
},
"type": "object"
},
"minItems": 1,
"type": "array"
},
"currency": {
"description": "ISO 4217 currency code matching the ad account's currency (e.g. `USD`).",
"maxLength": 3,
"minLength": 3,
"type": "string"
},
"customLocations": {
"description": "Point-radius geo (Meta `geo_locations.custom_locations`). Use for targeting a radius around a specific lat/long when no Meta city/region key fits. `distanceUnit` is required.",
"items": {
"properties": {
"address": {
"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": {
"exclusiveMinimum": 0,
"type": "number"
}
},
"required": [
"distanceUnit",
"latitude",
"longitude",
"radius"
],
"type": "object"
},
"type": "array"
},
"description": {
"description": "Link description, independent of `headline` and `body`: Meta's `link_data.description`, `video_data.link_description` on video, and the shared description of a `placementAssets` feed.",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"destination": {
"description": "Where the conversation opens when the ad is tapped. Set this OR `destinations`, not both.",
"enum": [
"whatsapp",
"messenger",
"instagram_direct"
],
"type": "string"
},
"destinations": {
"description": "Two or three messaging apps on ONE ad set, like Ads Manager's \"all messaging apps\". Set this OR `destination`, not both. The ad set gets Meta's combined destination_type (e.g.",
"items": {
"enum": [
"whatsapp",
"messenger",
"instagram_direct"
],
"type": "string"
},
"maxItems": 3,
"minItems": 2,
"type": "array",
"uniqueItems": true
},
"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": "ISO 8601 date or date-time, read like `startDate`; a date-only value ends at 23:59:59 local. Required when `budgetType` is `lifetime`.",
"type": "string"
},
"excludedLocations": {
"additionalProperties": true,
"description": "Geo to exclude, same shape as POST /apis/v1/ads/create (countries, countryGroups, regions, cities, zips, places, neighborhoods, customLocations).",
"type": "object"
},
"existingCampaignId": {
"description": "Creates the new messaging ad set (and its ads) under this EXISTING Meta campaign instead of a new one, e.g. several audience ad sets under one campaign. To add ads to an existing ad set instead, use `adSetId`. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.",
"pattern": "^\\d+$",
"type": "string"
},
"existingPostId": {
"description": "Alias of platformPostId, kept for existing callers. Sending both with different values is a 400.",
"minLength": 1,
"type": "string"
},
"gender": {
"description": "Restrict the audience by gender (Meta `genders`). Omit or send all for everyone; all is ignored in adSetId attach mode. Stored on the ad and read back in `targeting.gender`.",
"enum": [
"all",
"male",
"female"
],
"type": "string"
},
"headline": {
"description": "Single-creative shape only. Mutually exclusive with `creatives[]`. Required on a single image or video ad (including one built with `placementAssets`); not used by a `carouselCards` ad and not accepted with an existing post reference.",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"imageUrl": {
"description": "Image asset for single-creative shape. Mutually exclusive with `video` and with `creatives[]`. Required on the single-creative shape if neither `video` nor an existing post reference is supplied.",
"format": "uri",
"type": "string"
},
"incomeTier": {
"description": "Normalized household-income tier, same as POST /apis/v1/ads/create. Incompatible with housing, employment and credit specialAdCategories.",
"enum": [
"top_5",
"top_10",
"top_10_25",
"top_25_50"
],
"type": "string"
},
"interests": {
"items": {
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"type": "array"
},
"languages": {
"description": "Audience languages (Meta `locales`). A bare ISO 639-1 code targets all regional variants (\"en\" = all English), a region-qualified code a specific one (\"en_GB\", \"pt_BR\"); unknown codes are rejected.",
"items": {
"type": "string"
},
"type": "array"
},
"metros": {
"description": "DMA / metro-area geo targeting. `key` is Meta's metro id (e.g. `DMA:807`).",
"items": {
"properties": {
"key": {
"minLength": 1,
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
},
"name": {
"description": "Ad display name. Used to derive campaign / ad set names. On the multi-creative shape, each ad's Meta name gets a \" #N\" suffix (1-indexed) so Ads Manager shows them as a numbered batch.",
"minLength": 1,
"type": "string"
},
"neighborhoods": {
"description": "Meta neighborhood keys (from GET /apis/v1/ads/targeting/search).",
"items": {
"properties": {
"key": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
},
"objectStoryId": {
"description": "Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with platformPostId and fresh creative fields.",
"pattern": "^\\d+_\\d+$",
"type": "string"
},
"objective": {
"description": "Defaults to `OUTCOME_ENGAGEMENT`. `OUTCOME_SALES` and `OUTCOME_LEADS` require additional account configuration (Dataset linked to the WABA for sales) and may be rejected by Meta if missing.",
"enum": [
"OUTCOME_ENGAGEMENT",
"OUTCOME_SALES",
"OUTCOME_LEADS"
],
"type": "string"
},
"optimizeCardOrder": {
"description": "Only with `carouselCards` (a 400 without them). Single-creative shape; for `creatives[]` set it per entry. Sets the creative's `link_data.multi_share_optimized`. `false`: keeps the cards in the order given.",
"type": "boolean"
},
"pageId": {
"description": "Facebook Page the ad runs as, when the connection was granted several Pages. Defaults to the Page bound to the connection. Any Page granted to the connection is accepted; other ids answer 400 listing the granted Pages.",
"type": "string"
},
"placementAssets": {
"description": "A different image or video per placement on one messaging ad, e.g. a 4:5 image on Feed and a 9:16 image on Stories/Reels. Works on the single-creative shape and on attach (`adSetId`).",
"properties": {
"defaultImageUrl": {
"description": "Image mode. Catch-all image for any placement no rule matches. Required in image mode (Meta mandates a default rule).",
"format": "uri",
"type": "string"
},
"defaultThumbnailUrl": {
"description": "Video mode (optional). Poster image for the default video; Meta auto-generates one when omitted.",
"format": "uri",
"type": "string"
},
"defaultVideoUrl": {
"description": "Video mode. Catch-all video for any placement no rule matches. Required in video mode.",
"format": "uri",
"type": "string"
},
"rules": {
"description": "One entry per placement group you want to pin a specific asset to.",
"items": {
"properties": {
"body": {
"description": "One primary text pinned to this rule. Omit to inherit the top-level body.",
"minLength": 1,
"type": "string"
},
"description": {
"description": "One link description pinned to this rule. Omit to inherit the top-level description.",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"headline": {
"description": "One headline pinned to this rule. Omit to inherit the top-level headline.",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"imageUrl": {
"description": "Image mode. The image to deliver for this rule's placements.",
"format": "uri",
"type": "string"
},
"placements": {
"description": "Placements this asset is pinned to. At least one field must be set (an empty rule is invalid; that role is served by the default asset). Same enums as the top-level `placements` object.",
"properties": {
"audienceNetworkPositions": {
"items": {
"enum": [
"classic",
"rewarded_video"
],
"type": "string"
},
"type": "array"
},
"devicePlatforms": {
"items": {
"enum": [
"mobile",
"desktop"
],
"type": "string"
},
"type": "array"
},
"facebookPositions": {
"items": {
"enum": [
"feed",
"right_hand_column",
"marketplace",
"story",
"search",
"instream_video",
"facebook_reels",
"facebook_reels_overlay",
"profile_feed",
"notification"
],
"type": "string"
},
"type": "array"
},
"instagramPositions": {
"items": {
"enum": [
"stream",
"story",
"explore",
"explore_home",
"reels",
"profile_feed",
"ig_search",
"profile_reels"
],
"type": "string"
},
"type": "array"
},
"messengerPositions": {
"items": {
"enum": [
"messenger_home",
"sponsored_messages",
"story"
],
"type": "string"
},
"type": "array"
},
"publisherPlatforms": {
"items": {
"enum": [
"facebook",
"instagram",
"threads",
"messenger",
"audience_network",
"whatsapp",
"meta"
],
"type": "string"
},
"type": "array"
},
"threadsPositions": {
"items": {
"enum": [
"threads_stream"
],
"type": "string"
},
"type": "array"
},
"whatsappPositions": {
"items": {
"enum": [
"status"
],
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"thumbnailUrl": {
"description": "Video mode (optional). Poster image for this rule's video; auto-generated when omitted.",
"format": "uri",
"type": "string"
},
"videoUrl": {
"description": "Video mode. The video to deliver for this rule's placements.",
"format": "uri",
"type": "string"
}
},
"required": [
"placements"
],
"type": "object"
},
"maxItems": 10,
"minItems": 1,
"type": "array"
}
},
"required": [
"rules"
],
"type": "object"
},
"placements": {
"description": "Manual ad placements on the shared ad set. Omit for automatic placements.",
"properties": {
"audienceNetworkPositions": {
"items": {
"enum": [
"classic",
"rewarded_video"
],
"type": "string"
},
"type": "array"
},
"devicePlatforms": {
"description": "Restrict by device. Omit to deliver on both mobile and desktop.",
"items": {
"enum": [
"mobile",
"desktop"
],
"type": "string"
},
"type": "array"
},
"facebookPositions": {
"items": {
"enum": [
"feed",
"right_hand_column",
"marketplace",
"story",
"search",
"instream_video",
"facebook_reels",
"facebook_reels_overlay",
"profile_feed",
"notification"
],
"type": "string"
},
"type": "array"
},
"instagramPositions": {
"items": {
"enum": [
"stream",
"story",
"explore",
"explore_home",
"reels",
"profile_feed",
"ig_search",
"profile_reels"
],
"type": "string"
},
"type": "array"
},
"messengerPositions": {
"items": {
"enum": [
"messenger_home",
"sponsored_messages",
"story"
],
"type": "string"
},
"type": "array"
},
"publisherPlatforms": {
"description": "Top-level platforms to deliver on. A position field below is only honoured when its parent platform is included here.",
"items": {
"enum": [
"facebook",
"instagram",
"threads",
"messenger",
"audience_network",
"whatsapp",
"meta"
],
"type": "string"
},
"type": "array"
},
"threadsPositions": {
"items": {
"enum": [
"threads_stream"
],
"type": "string"
},
"type": "array"
},
"whatsappPositions": {
"items": {
"enum": [
"status"
],
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"places": {
"description": "Meta place keys (from GET /apis/v1/ads/targeting/search).",
"items": {
"properties": {
"key": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
},
"platformPostId": {
"description": "Messaging and CTWA only. Platform post or reel ID, the same input boostPost takes as platformPostId. Mutually exclusive with objectStoryId and fresh creative fields. Facebook IDs become object_story_id.",
"minLength": 1,
"type": "string"
},
"rawTargeting": {
"additionalProperties": true,
"description": "Meta targeting spec sent as the BASE layer of the ad set's `targeting`, exactly as POST /apis/v1/ads/create does.",
"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"
},
"regions": {
"description": "Region / state-level geo targeting. `key` is Meta's region ID (lookupable via GET /apis/v1/ads/targeting/search?type=region).",
"items": {
"properties": {
"key": {
"minLength": 1,
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
},
"roasAverageFloor": {
"description": "Decimal ROAS multiplier (e.g. `2.0` = 2.0× ROAS floor). Required when `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`; rejected otherwise. Meta enforces its own upper bound server-side.",
"exclusiveMinimum": 0,
"type": "number"
},
"savedTargetingId": {
"description": "ID of a saved_targeting audience (POST /apis/v1/ads/audiences), expanded as the base targeting. Precedence: savedTargetingId, then `targeting`, then the flat fields. 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"
},
"specialAdCategories": {
"description": "Meta special ad categories on the new campaign.",
"items": {
"enum": [
"HOUSING",
"EMPLOYMENT",
"CREDIT",
"ISSUES_ELECTIONS_POLITICS",
"FINANCIAL_PRODUCTS_SERVICES",
"ONLINE_GAMBLING_AND_GAMING"
],
"type": "string"
},
"type": "array"
},
"specialAdCategoryCountry": {
"description": "Countries the special ad category applies to. Requires specialAdCategories.",
"items": {
"type": "string"
},
"type": "array"
},
"startDate": {
"description": "When the ad set starts delivering. ISO 8601 date or date-time.",
"type": "string"
},
"status": {
"description": "Defaults to `ACTIVE`. `PAUSED` pauses only the top-most object this call creates: the new campaign (ad set and ads switched on), or, with `adSetId`, the new ads themselves.",
"enum": [
"ACTIVE",
"PAUSED"
],
"type": "string"
},
"targeting": {
"description": "Normalized, platform-agnostic ad-targeting spec. Every field is optional; an empty object targets the platform's default broadest audience.",
"properties": {
"ageMax": {
"description": "Maximum age. Same per-platform application and clamping as ageMin.",
"maximum": 100,
"minimum": 13,
"type": "integer"
},
"ageMin": {
"description": "Minimum age. Applied on Meta, TikTok, Pinterest, LinkedIn, X and Google Search/Display (Google excludes the age ranges outside the request). Rejected with 400 on OpenAI, Reddit and Google Performance Max / Demand Gen.",
"maximum": 100,
"minimum": 13,
"type": "integer"
},
"audienceExclude": {
"description": "Platform audience IDs to exclude; same ID formats as audienceInclude. Not supported on OpenAI (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.",
"items": {
"type": "string"
},
"type": "array"
},
"audienceInclude": {
"description": "Platform audience IDs to include, as returned by GET /apis/v1/ads/audiences: Meta: custom audience ids. TikTok: audience ids. Pinterest: customer list ids. LinkedIn: segment ids (the platformAudienceId from GET /apis/v1/ads/audiences). 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"
},
"behaviors": {
"description": "Behaviour entities from /apis/v1/ads/targeting/search?dimension=behavior (Meta, TikTok and LinkedIn). On TikTok they target people who, in the picked categories:",
"items": {
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"type": "array"
},
"cities": {
"description": "City targeting. Optional `radius` + `distanceUnit` extend beyond the city limits; both must be set together or both omitted. `radius` is only honoured on platforms whose capability map allows city radius (Meta).",
"items": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"distanceUnit": {
"description": "Required if radius is set.",
"enum": [
"mile",
"kilometer"
],
"type": "string"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"radius": {
"description": "Radius around the city. 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.",
"type": "number"
}
},
"required": [
"key"
],
"type": "object"
}
]
},
"type": "array"
},
"communities": {
"description": "Reddit only (400 elsewhere). Subreddits to target, by name, with or without the `r/` prefix (e.g. `['marketing', 'r/startups']`), as returned by /apis/v1/ads/targeting/search?dimension=community.",
"items": {
"minLength": 1,
"type": "string"
},
"type": "array"
},
"companySizes": {
"description": "LinkedIn B2B only. Single-letter size codes (A to I), or the full urn:li:staffCountRange:* URN from /apis/v1/ads/targeting/search?dimension=companySize.",
"items": {
"type": "string"
},
"type": "array"
},
"conversationKeywords": {
"description": "Reddit only (400 elsewhere). Keywords that place the ad in Reddit conversations about them, as returned by /apis/v1/ads/targeting/search?dimension=conversationKeyword.",
"items": {
"minLength": 1,
"type": "string"
},
"type": "array"
},
"countries": {
"description": "ISO 3166-1 alpha-2 country codes (e.g. ['US']).",
"items": {
"type": "string"
},
"type": "array"
},
"countryGroups": {
"description": "Meta only. Continents and trade blocs (`geo_locations.country_groups`), for targeting a whole region without listing its countries. Combines with `countries` rather than replacing it, and is also accepted under `excludedLocations`.",
"items": {
"enum": [
"africa",
"asia",
"europe",
"north_america",
"south_america",
"oceania",
"central_america",
"caribbean",
"eea",
"euro_area",
"nafta",
"mercosur",
"afta",
"apec",
"gcc",
"cisfta",
"emerging_markets",
"itunes_app_store",
"android_free_store",
"android_paid_store"
],
"type": "string"
},
"type": "array"
},
"customLocations": {
"description": "Point-radius (lat/lng) targeting (Meta custom_locations / Google proximity). Honoured on Meta and Google; ignored on platforms without radius support.",
"items": {
"properties": {
"address": {
"description": "Optional label, sent to Meta as `address_string`. latitude/longitude take precedence for the pin location.",
"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": {
"description": "Positive radius around the point.",
"type": "number"
}
},
"required": [
"distanceUnit",
"latitude",
"longitude",
"radius"
],
"type": "object"
},
"type": "array"
},
"excludedCommunities": {
"description": "Reddit only (400 elsewhere). Subreddits to exclude, named like `communities`.",
"items": {
"minLength": 1,
"type": "string"
},
"type": "array"
},
"excludedConversationKeywords": {
"description": "Reddit only (400 elsewhere). Conversation keywords to keep the ad away from.",
"items": {
"minLength": 1,
"type": "string"
},
"type": "array"
},
"excludedLocations": {
"description": "Geo to exclude from the audience. Mirrors the inclusion geo shape. Meta (excluded_geo_locations): excluded cities can carry a radius catchment, and excluded custom (lat/lng) pins are supported.",
"properties": {
"cities": {
"description": "Cities to exclude. Optional `radius` + `distanceUnit` exclude a catchment around the city (both must be set together or both omitted); Meta honours the radius on excluded cities.",
"items": {
"properties": {
"distanceUnit": {
"description": "Required if radius is set.",
"enum": [
"mile",
"kilometer"
],
"type": "string"
},
"key": {
"type": "string"
},
"radius": {
"description": "Radius around the excluded city. Requires distanceUnit.",
"type": "number"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
},
"countries": {
"items": {
"type": "string"
},
"type": "array"
},
"countryGroups": {
"description": "Meta only. Continents and trade blocs to exclude (`excluded_geo_locations.country_groups`).",
"items": {
"enum": [
"africa",
"asia",
"europe",
"north_america",
"south_america",
"oceania",
"central_america",
"caribbean",
"eea",
"euro_area",
"nafta",
"mercosur",
"afta",
"apec",
"gcc",
"cisfta",
"emerging_markets",
"itunes_app_store",
"android_free_store",
"android_paid_store"
],
"type": "string"
},
"type": "array"
},
"customLocations": {
"description": "Point-radius (lat/lng) pins to exclude (Meta excluded_geo_locations.custom_locations). Mirrors the inclusion customLocations shape.",
"items": {
"properties": {
"address": {
"description": "Optional label, sent to Meta as `address_string`. latitude/longitude take precedence for the pin location.",
"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": {
"description": "Positive radius around the point.",
"type": "number"
}
},
"required": [
"distanceUnit",
"latitude",
"longitude",
"radius"
],
"type": "object"
},
"type": "array"
},
"neighborhoods": {
"description": "Named neighbourhood areas to exclude. `key` from /apis/v1/ads/targeting/search.",
"items": {
"properties": {
"key": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
},
"places": {
"description": "Named points of interest to exclude. `key` from /apis/v1/ads/targeting/search.",
"items": {
"properties": {
"key": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
},
"regions": {
"items": {
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
},
"zips": {
"items": {
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"gender": {
"description": "Restrict by gender. 'all' (default) targets everyone.",
"enum": [
"all",
"male",
"female"
],
"type": "string"
},
"incomeTier": {
"description": "Normalized household-income tier (ZIP/percentile based). Meta and TikTok express all four. Google maps only `top_10` (its INCOME_RANGE_90_UP); other tiers on Google, and any income tier on LinkedIn / X / Pinterest, are rejected.",
"enum": [
"top_5",
"top_10",
"top_10_25",
"top_25_50"
],
"type": "string"
},
"industries": {
"description": "LinkedIn B2B only. Industry URN id fragments, or the full urn:li:industry:* URN from /apis/v1/ads/targeting/search?dimension=industry.",
"items": {
"type": "string"
},
"type": "array"
},
"interests": {
"description": "Interest entities from /apis/v1/ads/targeting/search?dimension=interest. Each carries the platform's opaque id.",
"items": {
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"type": "array"
},
"jobFunctions": {
"description": "LinkedIn B2B only. Function URN id fragments, or the full urn:li:function:* URN from /apis/v1/ads/targeting/search?dimension=jobFunction.",
"items": {
"type": "string"
},
"type": "array"
},
"languages": {
"description": "Language codes restricting the audience by language. Applied on Meta, Google, TikTok, LinkedIn, X, Pinterest and Reddit; rejected with 400 on OpenAI. A code the platform cannot target returns 400 listing the ones it can.",
"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` is the platform location ID from /apis/v1/ads/targeting/search?dimension=geo&geoType=region. An entry may also be that id as a plain string (`\"20321\"` is `{ key: \"20321\" }`).",
"items": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
}
]
},
"type": "array"
},
"seniorities": {
"description": "LinkedIn B2B only. Seniority URN id fragments, or the full urn:li:seniority:* URN from /apis/v1/ads/targeting/search?dimension=seniority.",
"items": {
"type": "string"
},
"type": "array"
},
"skills": {
"description": "LinkedIn B2B only. Member skills (e.g. Python, Recruiting): skill URN id fragments, or the full urn:li:skill:* URN from /apis/v1/ads/targeting/search?dimension=skill. Values are ORed; the facet is ANDed with the other facets.",
"items": {
"type": "string"
},
"type": "array"
},
"userDevice": {
"description": "Meta only. Device models such as iPhone. Emitted as user_device. May also be supplied inside targeting.",
"items": {
"minLength": 1,
"type": "string"
},
"minItems": 1,
"type": "array"
},
"userOs": {
"description": "Meta only. Operating systems and version ranges, such as iOS_ver_14.0_and_above or Android. Emitted as user_os. May also be supplied inside targeting.",
"items": {
"minLength": 1,
"type": "string"
},
"minItems": 1,
"type": "array"
},
"workEmployers": {
"description": "Meta only. Employer entities from /apis/v1/ads/targeting/search?dimension=workEmployer.",
"items": {
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"type": "array"
},
"workIndustries": {
"description": "Meta only. Work-industry entities from /apis/v1/ads/targeting/search?dimension=workIndustry. Not interchangeable with the LinkedIn `industries` URN fragments.",
"items": {
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"type": "array"
},
"workPositions": {
"description": "Meta only. Job title entities from /apis/v1/ads/targeting/search?dimension=workPosition. Not interchangeable with the LinkedIn `jobTitles` URN fragments.",
"items": {
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"type": "array"
},
"zips": {
"description": "Postal/ZIP targeting. `key` is the platform's postal location ID (e.g. Meta `US:94304`). Supported on Meta, Google, TikTok, Pinterest, X.",
"items": {
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"tracking": {
"description": "Ad tracking. Meta, plus `urlTags` on ChatGPT (OpenAI) and `pixelId` on Reddit. Meta: attaches pixel measurement to the ad regardless of the optimization goal (the \"Website events\" tracking row in Ads Manager).",
"properties": {
"pixelId": {
"description": "Meta Pixel ID to attach for offsite-conversion measurement, or the Reddit pixel of the new ad group.",
"type": "string"
},
"urlTags": {
"description": "Click-URL params. Meta: stored on the creative as `url_tags` and returned by GET /apis/v1/ads/{adId}/tracking-tags.",
"items": {
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"key",
"value"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"userDevice": {
"description": "Meta `user_device`.",
"items": {
"type": "string"
},
"minItems": 1,
"type": "array"
},
"userOs": {
"description": "Meta `user_os`, e.g. [\"iOS_ver_14.0_and_above\"].",
"items": {
"type": "string"
},
"minItems": 1,
"type": "array"
},
"validateOnly": {
"description": "Dry-runs the ad on Meta with execution_options validate_only, as ONE inline campaign + ad set + creative + ad (or creative + ad on the existing ad set with `adSetId`). Nothing is uploaded, created or stored; media is checked by URL.",
"type": "boolean"
},
"video": {
"description": "Video creative for single-creative shape. Mutually exclusive with `imageUrl` and with `creatives[]`. Required on the single-creative shape if neither `imageUrl` nor an existing post reference is supplied.",
"properties": {
"id": {
"description": "Reuse a video already uploaded to this ad account (list them with GET /apis/v1/ads/videos) instead of re-uploading. Wins over `url`. Provide either `url` or `id`.",
"type": "string"
},
"thumbnailUrl": {
"description": "OPTIONAL: when omitted, the poster is auto-generated from Meta's own preferred video thumbnail. When Meta produces no candidate the request fails with a 502 platform_error (reason: video_thumbnail_unavailable).",
"format": "uri",
"type": "string"
},
"url": {
"description": "Public URL of the video to upload. Provide either `url` or `id`.",
"format": "uri",
"type": "string"
}
},
"type": "object"
},
"welcomeMessage": {
"description": "Custom chat welcome message (Meta's `page_welcome_message`, \"Mensaje de bienvenida\" / \"Mensaje predefinido\" in Ads Manager). Single-creative shape only; for `creatives[]` set it per entry.",
"properties": {
"prefillText": {
"description": "Message put into the user's text input, ready to send. Replaces Meta's default (\"Hi! I want more info.\"). Lets one ad steer the opening message toward what it promotes (e.g. a specific product). Exactly one of prefillText or quickReplies.",
"minLength": 1,
"type": "string"
},
"quickReplies": {
"description": "Tappable chips under the greeting instead of a prefilled message. Exactly one of prefillText or quickReplies. Put your own campaign or ad key in each payload.",
"items": {
"properties": {
"payload": {
"maxLength": 1000,
"minLength": 1,
"type": "string"
},
"title": {
"description": "Chip label the person taps.",
"maxLength": 20,
"minLength": 1,
"type": "string"
}
},
"required": [
"payload",
"title"
],
"type": "object"
},
"maxItems": 13,
"minItems": 1,
"type": "array"
},
"text": {
"description": "Greeting shown when the chat opens. Replaces Meta's default (\"Hi! Can we help you?\").",
"minLength": 1,
"type": "string"
}
},
"required": [
"text"
],
"type": "object"
},
"whatsappPhoneNumber": {
"description": "WhatsApp only. Optional E.164 number already paired with the Facebook Page. Omit to let Meta select the paired number. Sent to the creative CTA and, when creating a new ad set, its promoted_object.",
"pattern": "^\\+[1-9]\\d{6,14}$",
"type": "string"
},
"workEmployers": {
"items": {
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"type": "array"
},
"workIndustries": {
"items": {
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"type": "array"
},
"workPositions": {
"items": {
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"type": "array"
},
"workflowId": {
"description": "A workflow in the ad account's profile, stored on the ad. 404 when no such workflow exists in the profile.",
"pattern": "^[a-fA-F0-9]{24}$",
"type": "string"
},
"zips": {
"description": "ZIP / postal-code geo targeting. `key` is the platform's postal id resolved via /apis/v1/ads/targeting/search.",
"items": {
"properties": {
"key": {
"minLength": 1,
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"adAccountId",
"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
Besides the required list, the request must use EXACTLY ONE of these shapes: Single-creative: headline, body, and one of imageUrl / video, OR platformPostId / objectStoryId to reuse an organic post.
Meta ad account ID, e.g. act_123456789.
Minimum string length:
1Ad display name. Used to derive campaign / ad set names. On the multi-creative shape, each ad's Meta name gets a " #N" suffix (1-indexed) so Ads Manager shows them as a numbered batch.
Minimum string length:
1Attaches the creatives to this EXISTING messaging ad set instead of building a campaign, so the ad set keeps its learning phase. Its destination_type must match the ad's destination. 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 set this request provisions. Omitted keeps - Ad Set. Ignored with adSetId.
Maximum string length:
255Ad-set-level status, same semantics as POST /apis/v1/ads/create. Sets the new ad set's switch alone and overrides status for it.
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's Advantage+ audience expansion. 0 (default) keeps targeting strict; 1 lets Meta expand beyond the supplied targeting when its delivery system finds better matches. Always sent on CREATE (Meta requires it).
Available options:
0, 1 Required range:
13 <= x <= 65Required range:
13 <= x <= 65Custom or lookalike audience ids to exclude. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.
Minimum array length:
1Custom audience ID to target. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.
Custom or lookalike audience ids to include. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.
Minimum array length:
1Behavior ids from /apis/v1/ads/targeting/search?dimension=behavior. Meta: each dimension is its own flexible_spec entry (OR within, AND across). TikTok: video/creator interaction categories, sent as the ad group's actions.
Show child attributes
Show child attributes
Whole currency units (e.g. 5 = $5.00 on a USD account). Required when bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP; rejected otherwise.
Meta bid strategy applied to the shared ad set. Defaults to LOWEST_COST_WITHOUT_CAP (auto-bid) when omitted. LOWEST_COST_WITH_BID_CAP and COST_CAP require bidAmount. LOWEST_COST_WITH_MIN_ROAS requires roasAverageFloor.
Available options:
LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS Primary text shown above the image / video. Single-creative shape only. Mutually exclusive with creatives[].
Minimum string length:
1Budget amount in the ad account's currency major units (e.g. dollars for USD, not cents). Must be > 0. Required unless adSetId is set (the ad set owns it) or existingCampaignId names a campaign with a campaign budget.
Where the budget lives. adset (default) puts it on the new ad set. campaign creates an Advantage campaign budget (CBO): the budget and bid strategy sit on the campaign and the ad set inherits them, same as POST /apis/v1/ads/create.
Available options:
adset, campaign Required unless adSetId is set or existingCampaignId names a campaign with a campaign budget. lifetime requires endDate.
Available options:
daily, lifetime Exact name for the campaign this request provisions. Omitted keeps - Campaign. Ignored with adSetId (the ad set already has a campaign).
Maximum string length:
255Campaign-level status, same semantics as POST /apis/v1/ads/create. Defaults to status. PAUSED: holds the new campaign off while the ad set and ads switch on (one resume call brings the whole hierarchy live).
Available options:
ACTIVE, PAUSED Messaging and CTWA only (a 400 on POST /apis/v1/ads/call). A hand-built carousel of 2-10 image cards, sent to Meta in the given order as link_data.child_attachments.
Required array length:
2 - 10 elementsShow child attributes
Show child attributes
City-level geo targeting for local CTWA campaigns. Each entry maps to Meta's TargetingGeoLocationCity; key is Meta's city ID. radius and distance_unit are coupled: set both or neither.
Show child attributes
Show child attributes
The ads connection (adc_...), when not sent as the connectionId query parameter.
Pattern:
^adc_[0-9A-Za-z]+$ISO 3166-1 alpha-2 country codes. Defaults to ["US"] only when no other geo (cities, regions, zips, metros, customLocations) is supplied.
Required string length:
2Meta only. Continents and trade blocs (geo_locations.country_groups), for targeting a whole region without listing its countries. Combines with countries rather than replacing it, and is also accepted under excludedLocations.
Available options:
africa, asia, europe, north_america, south_america, oceania, central_america, caribbean, eea, euro_area, nafta, mercosur, afta, apec, gcc, cisfta, emerging_markets, itunes_app_store, android_free_store, android_paid_store 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
Multi-creative shape: N CTWA ads under one campaign + one ad set, sharing budget and targeting. Fresh and existing creatives can be mixed. Each entry supplies headline, body, and image/video, or a platformPostId or objectStoryId reference.
Minimum array length:
1Show child attributes
Show child attributes
ISO 4217 currency code matching the ad account's currency (e.g. USD).
Required string length:
3Point-radius geo (Meta geo_locations.custom_locations). Use for targeting a radius around a specific lat/long when no Meta city/region key fits. distanceUnit is required.
Show child attributes
Show child attributes
Link description, independent of headline and body: Meta's link_data.description, video_data.link_description on video, and the shared description of a placementAssets feed.
Required string length:
1 - 255Where the conversation opens when the ad is tapped. Set this OR destinations, not both.
Available options:
whatsapp, messenger, instagram_direct Two or three messaging apps on ONE ad set, like Ads Manager's "all messaging apps". Set this OR destination, not both. The ad set gets Meta's combined destination_type (e.g.
Required array length:
2 - 3 elementsAvailable options:
whatsapp, messenger, 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:
100ISO 8601 date or date-time, read like startDate; a date-only value ends at 23:59:59 local. Required when budgetType is lifetime.
Geo to exclude, same shape as POST /apis/v1/ads/create (countries, countryGroups, regions, cities, zips, places, neighborhoods, customLocations).
Creates the new messaging ad set (and its ads) under this EXISTING Meta campaign instead of a new one, e.g. several audience ad sets under one campaign. To add ads to an existing ad set instead, use adSetId. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.
Pattern:
^\d+$Alias of platformPostId, kept for existing callers. Sending both with different values is a 400.
Minimum string length:
1Restrict the audience by gender (Meta genders). Omit or send all for everyone; all is ignored in adSetId attach mode. Stored on the ad and read back in targeting.gender.
Available options:
all, male, female Single-creative shape only. Mutually exclusive with creatives[]. Required on a single image or video ad (including one built with placementAssets); not used by a carouselCards ad and not accepted with an existing post reference.
Required string length:
1 - 255Image asset for single-creative shape. Mutually exclusive with video and with creatives[]. Required on the single-creative shape if neither video nor an existing post reference is supplied.
Normalized household-income tier, same as POST /apis/v1/ads/create. Incompatible with housing, employment and credit specialAdCategories.
Available options:
top_5, top_10, top_10_25, top_25_50 Show child attributes
Show child attributes
Audience languages (Meta locales). A bare ISO 639-1 code targets all regional variants ("en" = all English), a region-qualified code a specific one ("en_GB", "pt_BR"); unknown codes are rejected.
DMA / metro-area geo targeting. key is Meta's metro id (e.g. DMA:807).
Show child attributes
Show child attributes
Meta neighborhood keys (from GET /apis/v1/ads/targeting/search).
Show child attributes
Show child attributes
Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with platformPostId and fresh creative fields.
Pattern:
^\d+_\d+$Defaults to OUTCOME_ENGAGEMENT. OUTCOME_SALES and OUTCOME_LEADS require additional account configuration (Dataset linked to the WABA for sales) and may be rejected by Meta if missing.
Available options:
OUTCOME_ENGAGEMENT, OUTCOME_SALES, OUTCOME_LEADS Only with carouselCards (a 400 without them). Single-creative shape; for creatives[] set it per entry. Sets the creative's link_data.multi_share_optimized. false: keeps the cards in the order given.
Facebook Page the ad runs as, when the connection was granted several Pages. Defaults to the Page bound to the connection. Any Page granted to the connection is accepted; other ids answer 400 listing the granted Pages.
A different image or video per placement on one messaging ad, e.g. a 4:5 image on Feed and a 9:16 image on Stories/Reels. Works on the single-creative shape and on attach (adSetId).
Show child attributes
Show child attributes
Manual ad placements on the shared ad set. Omit for automatic placements.
Show child attributes
Show child attributes
Meta place keys (from GET /apis/v1/ads/targeting/search).
Show child attributes
Show child attributes
Messaging and CTWA only. Platform post or reel ID, the same input boostPost takes as platformPostId. Mutually exclusive with objectStoryId and fresh creative fields. Facebook IDs become object_story_id.
Minimum string length:
1Meta targeting spec sent as the BASE layer of the ad set's targeting, exactly as POST /apis/v1/ads/create does.
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
Region / state-level geo targeting. key is Meta's region ID (lookupable via GET /apis/v1/ads/targeting/search?type=region).
Show child attributes
Show child attributes
Decimal ROAS multiplier (e.g. 2.0 = 2.0× ROAS floor). Required when bidStrategy is LOWEST_COST_WITH_MIN_ROAS; rejected otherwise. Meta enforces its own upper bound server-side.
ID of a saved_targeting audience (POST /apis/v1/ads/audiences), expanded as the base targeting. Precedence: savedTargetingId, then targeting, then the flat fields. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.
Meta special ad categories on the new campaign.
Available options:
HOUSING, EMPLOYMENT, CREDIT, ISSUES_ELECTIONS_POLITICS, FINANCIAL_PRODUCTS_SERVICES, ONLINE_GAMBLING_AND_GAMING Countries the special ad category applies to. Requires specialAdCategories.
When the ad set starts delivering. ISO 8601 date or date-time.
Defaults to ACTIVE. PAUSED pauses only the top-most object this call creates: the new campaign (ad set and ads switched on), or, with adSetId, the new ads themselves.
Available options:
ACTIVE, PAUSED Normalized, platform-agnostic ad-targeting spec. Every field is optional; an empty object targets the platform's default broadest audience.
Show child attributes
Show child attributes
Ad tracking. Meta, plus urlTags on ChatGPT (OpenAI) and pixelId on Reddit. Meta: attaches pixel measurement to the ad regardless of the optimization goal (the "Website events" tracking row in Ads Manager).
Show child attributes
Show child attributes
Meta user_device.
Minimum array length:
1Meta user_os, e.g. ["iOS_ver_14.0_and_above"].
Minimum array length:
1Dry-runs the ad on Meta with execution_options validate_only, as ONE inline campaign + ad set + creative + ad (or creative + ad on the existing ad set with adSetId). Nothing is uploaded, created or stored; media is checked by URL.
Video creative for single-creative shape. Mutually exclusive with imageUrl and with creatives[]. Required on the single-creative shape if neither imageUrl nor an existing post reference is supplied.
Show child attributes
Show child attributes
Custom chat welcome message (Meta's page_welcome_message, "Mensaje de bienvenida" / "Mensaje predefinido" in Ads Manager). Single-creative shape only; for creatives[] set it per entry.
Show child attributes
Show child attributes
WhatsApp only. Optional E.164 number already paired with the Facebook Page. Omit to let Meta select the paired number. Sent to the creative CTA and, when creating a new ad set, its promoted_object.
Pattern:
^\+[1-9]\d{6,14}$Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
A workflow in the ad account's profile, stored on the ad. 404 when no such workflow exists in the profile.
Pattern:
^[a-fA-F0-9]{24}$ZIP / postal-code geo targeting. key is the platform's postal id resolved via /apis/v1/ads/targeting/search.
Show child attributes
Show child attributes