Boost post as ad
Changed onTurns 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. 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.
accountId may be a Facebook, Instagram or Meta ads (business login) connection. A business-login connection has no posting account, so pass the post as platformPostId (Facebook pageId_postId or an Instagram media id); a Zernio postId is a 400 there.
For X, accountId may be the posting X account or its X Ads connection: either resolves the other on the same profile. A Zernio postId on an X Ads connection resolves through its X account, and is a 400 when the profile has none (pass platformPostId instead).
Reddit. accountId is the Reddit Ads connection (platform redditads). Pass the Reddit post as platformPostId (t3_abc123 or the bare id), or a Zernio postId, which resolves through the Reddit account connected on the same profile (400 when there is none). Reddit promotes only posts made by a profile of the ad account: a post by any other author returns 422. Goals are traffic, awareness, conversions, video_views (the post must be a video, 422 otherwise) and lead_generation; conversions and lead_generation need a pixel that already received the event (see promotedObject). leadGenFormId returns 400: Reddit retired its native lead forms, so lead_generation sends people to linkUrl and optimizes toward the pixel's Lead event. Each boost creates a campaign, an ad group carrying the budget, the targeting and the bid, and the ad. bidStrategy sets the ad group's bid: LOWEST_COST_WITHOUT_CAP (or omitted) is automatic bidding (BIDLESS), LOWEST_COST_WITH_BID_CAP is MANUAL_BIDDING with bidAmount as the bid, COST_CAP is MAXIMIZE_VOLUME with bidAmount as the cap; any other strategy returns 422 before anything is created.
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).
Request
- Base URL: https://zernio.com/api
- URL: https://zernio.com/api/v1/ads/boost
- Auth: HTTP bearer
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. A request cut off mid-handler (for example by a function timeout) can leave its key in progress, answering 409 until the key expires after 24 hours.
Request body
Example request
{
"creativeFeatures": {
"auto_promotion_tag": "OPT_IN"
},
"currency": "USD",
"locationTargetingType": "presence"
}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",
"creativeFeatures": {
"auto_promotion_tag": "OPT_IN"
},
"carouselCards": [
{
"callToAction": "SHOP_NOW"
}
],
"servingHoldReasons": [
"UNDER_REVIEW"
],
"whatsappPhoneNumber": "+12025550123"
}
}
}Changes
- info
added the optional property
//to the response with the status
- info
- info
added the optional property
//to the response with the status
- info