Flexible ad
Give Meta multiple creatives plus copy variations and let it optimise the mix.
A flexible ad hands Meta several creatives and several copy variations; Meta assembles and optimises the best-performing combinations automatically.
When to use this
You want Meta to test creative and copy permutations rather than fix one layout.
Example body
POST /meta/launches
Every key applicable to a flexible ad, with sample values. Required: adName, adSets, creatives[]._id, adProfiles, cta, webLink.
{
"adAccountId": "01H8Y4...",
"platform": "meta",
"ads": [
{
"adName": "Spring Flexible",
"adSets": ["123456789012345"],
"creativeDetails": {
"groupType": "flexible",
"creatives": [{ "_id": "01H8YA..." }, { "_id": "01H8YB..." }, { "_id": "01H8YC..." }]
},
"adProfiles": {
"facebook_page_id": "123456789012345",
"instagram_account_id": "987654321098765",
"page_backed_instagram_account_id": null
},
"cta": "SHOP_NOW",
"defaultPrimaryText": "Spring is here.",
"primaryTextVariations": ["Up to 40% off spring styles", "Spring drop — shop now"],
"defaultHeadline": "Spring Sale",
"headlineVariations": ["40% off", "New season, new looks"],
"adDescription": "Free shipping on orders over $50.",
"descriptionVariations" : ["Free shipping on orders over $50.", "Flat 40% off on orders over $80."],
"webLink": "https://example.com/spring",
"displayLink": "example.com/spring",
"utm": "utm_source=facebook&utm_medium=cpc&utm_campaign=spring",
"leadGenFormId": null,
"adSchedule": { "startDate": "2026-06-01T00:00:00Z", "endDate": "2026-06-30T23:59:59Z" },
"promoCodeDetails": { "type": "manual", "manualCodes": ["SPRING40", "EARLYBIRD"] },
"aiMediaDisclosure": true
}
]
}Full schema: Create a launch.
Required fields
adName,adSetscreativeDetails.creatives[]._idadProfiles— at least one offacebook_page_id/instagram_account_idctawebLink
The server mints ads[].id and creativeDetails.groupId.
Optional fields
defaultPrimaryText + primaryTextVariations, adDescription + descriptionVariations, defaultHeadline + headlineVariations (sending variations makes the matching default required; each set must be unique), adDescription, displayLink, utm, adSchedule, promoCodeDetails, leadGenFormId, aiMediaDisclosure.
Field notes
- **
primaryTextVariations/headlineVariations/descriptionVariations** — extra copy Meta can swap in. Thedefault*values are primary; variations are alternates. - Multiple
creatives[]— Meta picks among them per impression.
Gotchas
- Meta caps text variations at 5 each — extras are ignored.
