| account_id |
String |
Facebook or Instagram SocialAccount ID. |
|
| ad_account_id |
String |
Meta ad account ID, e.g. `act_123456789`. |
|
| name |
String |
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. |
|
| headline |
String |
Single-creative shape only. Mutually exclusive with `creatives[]`. |
[optional] |
| body |
String |
Primary text shown above the image / video. Single-creative shape only. Mutually exclusive with `creatives[]`. |
[optional] |
| image_url |
String |
Image asset for single-creative shape. Mutually exclusive with `video` and with `creatives[]`. Required on the single-creative shape if `video` is not supplied. |
[optional] |
| video |
CtwaAdRequestBodyVideo |
|
[optional] |
| welcome_message |
CtwaAdRequestBodyWelcomeMessage |
|
[optional] |
| creatives |
Array<CtwaAdRequestBodyCreativesInner> |
Multi-creative shape: N CTWA ads under one campaign + one ad set, sharing budget and targeting. Mutually exclusive with the top-level single-creative fields (`headline` / `body` / `imageUrl` / `video`): setting both is a 400, unlike `POST /v1/ads/create` where the top-level fields are silently ignored in multi-creative mode. Each entry must supply its own headline, body, and exactly one of `imageUrl` / `video`. |
[optional] |
| ad_set_id |
String |
Attach the creatives to this EXISTING messaging ad set instead of building a campaign, so the ad set keeps its learning phase. It then owns budget, targeting and schedule, so `budgetAmount`, `budgetType`, `endDate`, `objective`, `countries`, `interests`, `audienceId` and `campaignStatus` are rejected with a 400 alongside it. Its `destination_type` must match the ad's destination. |
[optional] |
| budget_amount |
Float |
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, where the ad set owns it. |
[optional] |
| budget_type |
String |
Required unless `adSetId` is set. |
[optional] |
| currency |
String |
ISO 4217 currency code matching the ad account's currency (e.g. `USD`). Optional: Zernio resolves it from the ad account when omitted. The value selects the minor-unit exponent Zernio converts budget/bid amounts by before calling Meta (most currencies are cents; zero-decimal currencies like JPY/KRW are sent as-is). |
[optional] |
| end_date |
Time |
ISO 8601 datetime. Required when `budgetType` is `lifetime`. |
[optional] |
| countries |
Array<String> |
ISO 3166-1 alpha-2 country codes. Defaults to `["US"]` only when no other geo (`cities`, `regions`, `zips`, `metros`, `customLocations`) is supplied. |
[optional] |
| cities |
Array<CtwaAdRequestBodyCitiesInner> |
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. 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). |
[optional] |
| regions |
Array<CtwaAdRequestBodyRegionsInner> |
Region / state-level geo targeting. `key` is Meta's region ID (lookupable via GET /v1/ads/targeting/search?type=region). |
[optional] |
| zips |
Array<CtwaAdRequestBodyZipsInner> |
ZIP / postal-code geo targeting. `key` is the platform's postal id resolved via /v1/ads/targeting/search. |
[optional] |
| metros |
Array<CtwaAdRequestBodyZipsInner> |
DMA / metro-area geo targeting. `key` is Meta's metro id (e.g. `DMA:807`). |
[optional] |
| custom_locations |
Array<CreateStandaloneAdRequestCustomLocationsInner> |
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. |
[optional] |
| age_min |
Integer |
|
[optional] |
| age_max |
Integer |
|
[optional] |
| interests |
Array<CreateStandaloneAdRequestBehaviorsInner> |
|
[optional] |
| audience_id |
String |
Custom audience ID to target. |
[optional] |
| placements |
CtwaAdRequestBodyPlacements |
|
[optional] |
| advantage_audience |
Integer |
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). |
[optional] |
| objective |
String |
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. |
[optional] |
| status |
String |
Ad-level status. Defaults to `ACTIVE`. `PAUSED` skips activating the newly created ad(s) after Meta accepts them. |
[optional] |
| campaign_status |
String |
Campaign-level status, same semantics as `POST /v1/ads/create`. Defaults to `ACTIVE`. `PAUSED` holds activation at the campaign so it never spends before the advertiser reviews it, while the ad set and ad still switch on (one resume call brings the whole hierarchy live). Only meaningful when a new campaign is being created; rejected with a 400 alongside `adSetId` (the attach shape reuses an existing campaign). |
[optional] |
| bid_strategy |
String |
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`. CTWA's `optimization_goal` is fixed to `CONVERSATIONS`, but the bid strategy is independent. |
[optional] |
| bid_amount |
Float |
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. |
[optional] |
| roas_average_floor |
Float |
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. |
[optional] |
| dsa_beneficiary |
String |
Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26). Optional if the ad account has a default beneficiary: set it once via `PATCH /v1/ads/accounts` or in Meta Ads Manager, and Meta fills it in whenever the field is omitted. |
[optional] |
| dsa_payor |
String |
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. |
[optional] |
| regional_regulated_categories |
Array<String> |
Meta only. Regional regulation categories required when the ad set targets certain countries (e.g. BRAZIL_REGULATION, SINGAPORE_UNIVERSAL, TAIWAN_UNIVERSAL, THAILAND_UNIVERSAL, AUSTRALIA_FINSERV, INDIA_FINSERV, TAIWAN_FINSERV). Forwarded to the ad set. |
[optional] |
| regional_regulation_identities |
Hash<String, Integer> |
Meta only. Beneficiary/payer entity IDs required alongside regionalRegulatedCategories. Values are numeric IDs from the advertiser's Meta verification/authorization setup. Keys depend on the declared category: BRAZIL_REGULATION and THAILAND_UNIVERSAL use universal_beneficiary / universal_payer; SINGAPORE_UNIVERSAL uses singapore_universal_beneficiary / singapore_universal_payer; TAIWAN_UNIVERSAL uses taiwan_universal_beneficiary / taiwan_universal_payer; TAIWAN_FINSERV uses taiwan_finserv_beneficiary / taiwan_finserv_payer; AUSTRALIA_FINSERV uses australia_finserv_beneficiary / australia_finserv_payer; INDIA_FINSERV uses india_finserv_beneficiary / india_finserv_payer. Both beneficiary and payer must be included. If omitted and the advertiser has set defaults in Meta Ads Manager advertising settings, Meta auto-fills them. |
[optional] |
| phone_number |
String |
E.164 number the CALL_NOW CTA dials (e.g. +34600111222). |
|
| link_url |
String |
Website shown as the creative's link. Required: Meta rejects tel: as link_data.link; the phone number rides only the CTA. |
|