Sign in
Ad Campaigns

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.

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.

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).

post/v1/ads/boost

Headers

Idempotency-Keystring

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

creativeFeaturesMetaCreativeFeatures

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. auto_promotion_tag is an Advantage+ enhancement, not the Ads Manager Promotion setting. The deprecated standard_enhancements bundle is rejected by Meta.

postIdstring

Zernio post ID (provide this or platformPostId)

platformPostIdstring

Platform post ID (alternative to postId). Meta: a Page post id (<pageId>_<postId> or the bare post id) or an Instagram media id. On a Meta Ads business-login connection (platform metaads) the id is resolved live: an Instagram media id is boosted as that media, running as the Instagram account that owns it.

accountIdstring required

Zernio account id. Normally the connected posting account (facebook, instagram, tiktok, linkedin, pinterest, twitter) or a googleads account. TikTok: the TikTok Ads connection (platform tiktokads) is accepted too when the post brings its own authorization (sparkAuthCode or sparkPosts), so Spark ads need no organic TikTok account connected; such a call must use platformPostId, not postId.

adAccountIdstring required

Platform ad account ID

namestring required
campaignNamestring

Exact name for the campaign this boost provisions. Omitted keeps the default <name> - Campaign. Every platform: on LinkedIn it names the campaign group. Ignored on the Meta attach shape (adSetId), which creates no campaign.

adSetNamestring

Exact name for the ad-group level this boost provisions. Omitted keeps the default <name> - Ad Group. Meta: ad set; TikTok, Pinterest, Google: ad group; X: line item; LinkedIn: the campaign under the campaign group. Ignored on the Meta attach shape.

goal'engagement' | 'traffic' | 'awareness' | 'video_views' | 'lead_generation' | 'conversions' | 'app_promotion' required

Available goals vary by platform. Meta (Facebook/Instagram) and TikTok support all 7. LinkedIn supports all except app_promotion. X supports engagement, traffic, awareness, video_views, app_promotion. Pinterest and Google Ads support only engagement, traffic, awareness, video_views.

adSetIdstring

Meta, or TikTok with smartPlus: true. Attach the boosted post to this existing ad set instead of creating a campaign. On TikTok the id is an existing Smart+ ad group: the post is added as one more Spark ad in it (up to 30 per ad group), under the identity its sparkAuthCode creates; goal and budget are inherited from the Smart+ campaign; a regular ad group is rejected with a 400. Meta: The ad set then owns budget, schedule and targeting; sending those too is a 400.

existingCampaignIdstring

TikTok only. Create the ad group and the Spark ad under this existing TikTok campaign instead of creating a new campaign. The campaign keeps its own status and objective (the objective must fit goal). Cannot be combined with adSetId or smartPlus. On Meta use POST /v1/ads/create with existingCampaignId.

identityIdstring

TikTok only. The identity the ad runs as (the profile shown on the ad), from GET /v1/ads/tiktok-identities. Default: the connected TikTok account's own identity. Must be authorized on the advertiser or the call fails naming the available ones.

identityType'TT_USER' | 'CUSTOMIZED_USER' | 'BC_AUTH_TT'

TikTok only. Type of identityId; resolved from the advertiser's identity list when omitted.

budgetAmountnumber

Budget in whole currency units, the same flat field as POST /v1/ads/create. Required unless adSetId is set. Minimum varies: TikTok=$20, Pinterest=$5, others=$1

budgetType'daily' | 'lifetime'

Goes together with budgetAmount. lifetime requires schedule.endDate.

instagramAccountIdstring

Meta only. Instagram identity the ad runs AS (creative.instagram_user_id), overriding the account linked to the Page. Live-verified against a Page-post creative.

destinationType'INSTAGRAM_PROFILE' | 'WEBSITE' | 'ON_AD' | 'MESSENGER' | 'WHATSAPP' | 'INSTAGRAM_DIRECT'

Meta only. Ad-set destination_type: where the click LANDS, as opposed to instagramAccountId which is who the ad runs as. Independent of plain link CTAs and their goal. A messaging callToAction selects its destination automatically; an explicit destinationType must then match. Lead ads use ON_AD.

whatsappPhoneNumberstring

Meta WhatsApp only. E.164 number already paired with the Page. Omit to use the default pairing. Requires WHATSAPP_MESSAGE callToAction. Stored as creative.whatsappPhoneNumber on the ad.

currencystring

ISO 4217 currency code matching the ad account's currency. Meta only. 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).

startDatestring date-time

Ad-set start time (ISO 8601, e.g. "2026-06-10T09:00:00Z"), mapped to the ad set's start_time. When omitted the ad starts delivering immediately. Same field as on POST /v1/ads/create.

endDatestring date-time

Ad-set end time (ISO 8601), mapped to the ad set's end_time. Required for lifetime budgets. Same field as on POST /v1/ads/create.

locationTargetingType'presence' | 'presence_or_interest'

Google only. Who a campaign's location targeting reaches (Google's campaign.geo_target_type_setting.positive_geo_target_type). presence: people in, or regularly in, the targeted locations. presence_or_interest: also people searching for or showing interest in them. Omitted leaves Google's default, presence_or_interest. Accepted on Search, Display and Performance Max campaigns. Excluded locations always use presence (Google refuses presence_or_interest for exclusions on these campaign types).

rawTargetingobject

Meta only. A Meta-native targeting spec (e.g. { "geo_locations": { "cities": [{ "key": "...", "radius": 15, "distance_unit": "kilometer" }] } }). Sent alone it is forwarded unchanged. Use for advanced fields the structured object does not expose (flexible_spec, excluded audiences, business places, user_os, wireless_carrier).

Can be combined with targeting: rawTargeting is the BASE layer and the built camelCase spec is merged on top, key by key (camelCase wins on collision). The merge goes one level deep inside geo_locations and excluded_geo_locations (built sub-keys win; raw-only sub-keys such as location_types survive). Array values (flexible_spec, ...) are replaced as a whole key, never element-merged.

When rawTargeting is present the advantage_audience: 0 default that Zernio normally applies is no longer emitted, so it cannot clobber a targeting_automation sent in the raw spec. Meta requires targeting_automation on ad set creation, so include it in the raw spec, or send targeting.advantage_audience (0 or 1), which is merged over raw as targeting_automation.

bidStrategy'LOWEST_COST_WITHOUT_CAP' | 'LOWEST_COST_WITH_BID_CAP' | 'COST_CAP' | 'LOWEST_COST_WITH_MIN_ROAS'

Meta bid strategy. Same enum applies at campaign and ad-set level; ad-set value (when set) overrides campaign-level. Cross-field rules:

  • LOWEST_COST_WITHOUT_CAP (default): auto-bid, forbids bidAmount and roasAverageFloor.
  • LOWEST_COST_WITH_BID_CAP / COST_CAP: require bidAmount (whole currency units).
  • LOWEST_COST_WITH_MIN_ROAS: requires roasAverageFloor (decimal multiplier, 2.0 = 2.0x). Source: facebook-business-sdk-codegen api_specs/specs/enum_types.json (AdSet_bid_strategy, Campaign_bid_strategy).
bidAmountnumber

Deprecated: send it inside platformSpecificData instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400.

Bid cap in WHOLE currency units (USD: 5 = $5.00; JPY: 100 = ¥100). Required when bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP. Backward-compat: providing bidAmount without bidStrategy is treated as LOWEST_COST_WITH_BID_CAP.

roasAverageFloornumber

Deprecated: send it inside platformSpecificData instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400.

Minimum ROAS as a decimal multiplier (e.g. 2.0 = 2.0x ROAS). Required when bidStrategy is LOWEST_COST_WITH_MIN_ROAS. Sent to Meta as bid_constraints.roas_average_floor × 10000 (Meta uses fixed-point integers).

specialAdCategoriesstring[]

Meta only. Required for housing, employment, credit, or political ads.

specialAdCategoryCountrystring[]

Meta (metaads) only. 2-letter ISO country codes the special ad category applies to. Requires specialAdCategories to be set (400 otherwise).

regionalRegulatedCategoriesstring[]

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.

regionalRegulationIdentitiesobject

Meta only. Beneficiary/payer entity IDs for regionalRegulatedCategories. Values are numeric IDs from Meta verification. Keys vary by category (e.g. universal_beneficiary / universal_payer for BRAZIL_REGULATION and THAILAND_UNIVERSAL). If omitted, Meta uses Ads Manager defaults when configured.

linkUrlstring uri

Website URL for non-messaging CTA buttons. Send it with callToAction. Omit for messaging boosts.

Meta: adds a top-level call_to_action to the post-reference creative. This is what gives a traffic boost a clickable destination without replacing the creative and losing the post's social proof. Ignored when leadGenFormId is set, which supplies its own destination. Live-verified against a Page-post creative.

TikTok: maps to landing_page_url on the Spark Ad creative (AdcreateCreatives.landing_page_url); Spark Ads have no clickable destination without it.

Ignored on LinkedIn / Pinterest / X / Google, which infer the destination from the boosted post.

callToActionstring

CTA button label. Non-messaging CTAs require linkUrl. WHATSAPP_MESSAGE, MESSAGE_PAGE, and INSTAGRAM_MESSAGE do not require a URL and reject linkUrl.

Meta: the CTA enum of POST /v1/ads/create plus VIEW_INSTAGRAM_PROFILE, WHATSAPP_MESSAGE, MESSAGE_PAGE, and INSTAGRAM_MESSAGE. VIEW_INSTAGRAM_PROFILE requires linkUrl; the messaging CTAs select their destination automatically.

TikTok: pass-through to call_to_action on the Spark Ad creative; the platform validates the value. See TikTok's "Enumeration - Call-to-Action".

sparkAuthCodestring

TikTok-only. Spark Code (creator's auth_code) authorizing cross-creator Spark Ads: the advertiser can boost a video owned by a DIFFERENT TikTok account. Without this, boosts are limited to videos owned by the same account running the ads (same-BC creators only). The creator generates the code in their TikTok app's Promote settings and shares it with the advertiser. Maps to auth_code on the creative entry of /v2/ad/create/.

smartPlusboolean

TikTok only. Run the Spark post in a Smart+ campaign (goal conversions = Smart+ Web Conversions, lead_generation = Smart+ Lead Generation) instead of a regular campaign. Requires sparkAuthCode (the Smart+ ad runs the post under the identity that redeeming its Spark code creates; a Business Center-owned post is not accepted there) and promotedObject.pixelId + customEventType. app_promotion is not available on a Spark post. Rejected with a 400 on other platforms. A Smart+ Spark ad uses a dynamic CTA portfolio, sent as ad_configuration.call_to_action_id (TikTok does not accept a named call to action there): Zernio creates one per ad account and reuses it, and callToAction is rejected with a 400 on this path.

dsaBeneficiarystring

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.

dsaPayorstring

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.

leadGenFormIdstring

Lead Gen form ID to attach to the boosted ad's creative. REQUIRED when goal is lead_generation. On Meta this is the leadgen_forms ID (create one via POST /v1/ads/lead-forms). On LinkedIn this is the adForm ID (create one via POST /v1/ads/lead-forms with a LinkedIn account); the creative's leadgenCallToAction.destination is set to urn:li:adForm:{id}. Ignored for other goals.

status'ACTIVE' | 'PAUSED'

Meta, TikTok, LinkedIn, and Google. Publish state of the created entities. Omitted or ACTIVE publishes live (default); PAUSED creates them paused so you can review before they spend. On Meta a new campaign stays paused until explicitly activated; an attached ad is itself paused. On Google the pause is held on the campaign the boost creates (ad group and ad switched on), so PUT /v1/ads/campaigns/{campaignId}/status with active brings it live. On LinkedIn the whole campaign group, campaign, and creative hierarchy stays PAUSED (intendedStatus PAUSED on each).

budgetLevel'adset' | 'campaign'

Meta only, same semantics as POST /v1/ads/create: campaign = Advantage campaign budget (CBO), the budget and bid strategy sit on the campaign and the ad set inherits them. Default adset. Not allowed with adSetId.

bodiesstring[]

Meta only. Extra primary-text options Meta rotates on the boosted post (asset_feed_spec.bodies with DEGREES_OF_FREEDOM); the post keeps its own text as one of the options. Works for Facebook posts and Instagram media. Under a conversions or traffic goal Meta also wants a website URL on the options, taken from linkUrl (send it with a callToAction); engagement boosts need none.

optimizationGoalstring

Meta, or TikTok with goal: video_views. TikTok: ENGAGED_VIEW (6-second Focused View, the default) or ENGAGED_VIEW_FIFTEEN (15-second views), both billed per view (CPV); any other value is a 400. Meta: explicit ad-set optimization_goal override. When omitted, defaults to the value derived from goal. Messaging boosts always use CONVERSATIONS and reject another optimizationGoal. Otherwise the value must be compatible with the objective Meta derives from goal, not with the objective used by POST /v1/ads/create for the same goal name: boost maps goal: "engagement" to objective OUTCOME_AWARENESS, which accepts REACH, IMPRESSIONS, AD_RECALL_LIFT, or THRUPLAY-class values, and rejects POST_ENGAGEMENT (that value is only valid under OUTCOME_ENGAGEMENT, which create uses for the same goal name).

Example request

{
  "creativeFeatures": {
    "auto_promotion_tag": "OPT_IN"
  },
  "currency": "USD",
  "locationTargetingType": "presence"
}

Response

Ad created

messagestring

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"
    }
  }
}

Changes

Changed in 24 of the 56 revisions of this API.1478

  • 2c04683ce6949See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • a0d8f21b5abe1See the full diff
    • ○

      added the non-success response with the status

      response-non-success-status-added

  • dd3865482f9f15See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property /

      new-optional-request-property

    • ○

      added the new optional request property /

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      the request property / became optional

      request-property-became-optional

    • ○

      the request property / became optional

      request-property-became-optional

    • ○

      request property deprecated

      request-property-deprecated

    • ○

      request property deprecated

      request-property-deprecated

    • ○

      request property / deprecated

      request-property-deprecated

    • ○

      request property / deprecated

      request-property-deprecated

  • 339f59df69dd4See the full diff
    • ○

      added the optional property // to the response with the status

      response-optional-property-added

    • ○

      added the optional property // to the response with the status

      response-optional-property-added

    • ○

      added the optional property // to the response with the status

      response-optional-property-added

    • ○

      added the optional property // to the response with the status

      response-optional-property-added

  • eded32b628232See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

  • fdaf9a9fb1a73See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

  • be448f13ecdc3See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

  • 3e6ddf2a99ea1See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

  • 0dba7d004d753See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

  • 06acc34a70172See the full diff
    • ●

      removed the optional property // from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property // from the response with the status

      response-optional-property-removed

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog