Boost post as ad
Creates a paid ad from an existing published post, keeping the post's engagement. 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. It then owns budget, schedule and targeting, and sending any of those alongside adSetId is a 400 rather than a silent drop. budget is required only without adSetId.
instagramAccountId, destinationType, whatsappPhoneNumber and adSetId are Meta-only and return 400 on other platforms.
Messaging boosts (Meta). Use goal: engagement with callToAction: WHATSAPP_MESSAGE, MESSAGE_PAGE, or INSTAGRAM_MESSAGE. The CTA implies WHATSAPP, MESSENGER, or INSTAGRAM_DIRECT respectively; destinationType alone does not select a messaging CTA. Omit linkUrl only for messaging CTAs. Plain link CTAs keep their goal and link behavior when combined with an independent destinationType. The campaign uses OUTCOME_ENGAGEMENT and the ad set uses CONVERSATIONS with the promoted Page. Optional whatsappPhoneNumber selects a number already paired with that Page. Conflicting CTA/destination, instant form, goal, or optimizationGoal inputs return 400. Attach requires the target ad set destination to match. Existing post references preserve social proof; an Instagram reel rejected by Meta is not re-uploaded as a new post for a messaging boost.
Retries. Boosts are NOT idempotent and can take minutes when Meta requires re-hosting an Instagram video, so do not retry on client timeout. Send an Idempotency-Key header to make retries safe: same key and body replays the original 201, and distinct keys always create distinct ads. Without the header, an identical request is treated as a retry: while one is in flight it returns 409, and within 10 minutes of a completed boost it returns the already-created ad instead of creating another. To intentionally duplicate an ad, send distinct Idempotency-Keys (or vary the body, e.g. the name).
Headers
Optional client-generated unique key (e.g. a UUID) that makes retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409.
Request body
Example request
{
"creativeFeatures": {
"auto_promotion_tag": "OPT_IN"
},
"currency": "USD"
}Response
Ad created
Example response
{
"ad": {
"configuredStatus": "ACTIVE",
"creativeType": "video",
"metrics": {
"actions": {
"link_click": 160,
"post_engagement": 300,
"offsite_conversion.fb_pixel_purchase": 42
},
"actionValues": {
"offsite_conversion.fb_pixel_purchase": 2456.78,
"offsite_conversion.fb_pixel_add_to_cart": 980.5
},
"costPerAction": {
"link_click": 0.1052,
"offsite_conversion.fb_pixel_purchase": 4.0114
}
},
"platformObjective": "OUTCOME_SALES",
"optimizationGoal": "OFFSITE_CONVERSIONS",
"costType": "CPC",
"servingStatuses": [
"ACCOUNT_TOTAL_BUDGET_HOLD"
],
"platformAdAccountName": "Zernio - previously Late",
"bidAmount": 5,
"roasAverageFloor": 2,
"promotedObject": {
"custom_event_type": "PURCHASE"
},
"creative": {
"assetGroup": {
"finalUrl": "https://zernio.com",
"headlines": [
"Schedule posts",
"One social API",
"Build with Zernio"
],
"longHeadline": "Schedule social content from your app with Zernio",
"descriptions": [
"Connect your social accounts.",
"Publish and manage social content through one API."
],
"businessName": "Zernio",
"images": {
"landscape": [
"https://example.com/landscape.png"
],
"square": [
"https://example.com/square.png"
],
"logo": [
"https://example.com/logo.png"
]
}
},
"assetGroupResourceName": "customers/9122445560/assetGroups/123456789",
"servingHoldReasons": [
"UNDER_REVIEW"
],
"whatsappPhoneNumber": "+12025550123"
}
}
}