Zernio API Docs

Appearance

Create standalone ad ​

Creates a paid ad with custom creative across Meta, Google Ads, Pinterest, TikTok, X/Twitter, and LinkedIn. Supports three mutually-exclusive request shapes selected by the body, a legacy single-creative shape (all platforms, default), a Meta-only multi-creative shape via the creatives array (one ad set with N ads sharing budget and targeting), and a Meta-only attach shape via adSetId (adds one new ad to an existing ad set). Per-platform required fields, budget minimums, and video-ad rules are documented on each property below. LinkedIn creates a Single Image or Single Video Ad backed by a Direct Sponsored Content "dark post" authored by a Company Page (see organizationId); supported goals are engagement, traffic, awareness, and video_views (video ads use the video field; video_views requires a video), and traffic ads require linkUrl.

POST /v1/ads/create ​

Creates a paid ad with custom creative across Meta, Google Ads, Pinterest, TikTok, X/Twitter, and LinkedIn. Supports three mutually-exclusive request shapes selected by the body, a legacy single-creative shape (all platforms, default), a Meta-only multi-creative shape via the creatives array (one ad set with N ads sharing budget and targeting), and a Meta-only attach shape via adSetId (adds one new ad to an existing ad set). Per-platform required fields, budget minimums, and video-ad rules are documented on each property below. LinkedIn creates a Single Image or Single Video Ad backed by a Direct Sponsored Content "dark post" authored by a Company Page (see organizationId); supported goals are engagement, traffic, awareness, and video_views (video ads use the video field; video_views requires a video), and traffic ads require linkUrl.

Request body ​

Content-Type: application/json

  • accountId (string) required
  • adAccountId (string) required
  • name (string) required
  • goal (string) (enum: engagement, traffic, awareness, video_views, lead_generation, conversions, app_promotion) — Required on legacy + multi-creative shapes. Inherited from the ad set on the attach shape. Available goals vary by platform. Meta-specific: conversions requires promotedObject.pixelId + `promotedO...
  • budgetAmount (number) — Required on legacy + multi-creative shapes. Inherited on attach.
  • budgetType (string) (enum: daily, lifetime) — Required on legacy + multi-creative shapes. Inherited on attach.
  • currency (string)
  • headline (string) — Required for Meta, Google, Pinterest, and LinkedIn on legacy + attach shapes (skip for multi-creative — use creatives[].headline). Ignored for TikTok and X/Twitter. Max: Meta=255, Google=30, Pintere...
  • longHeadline (string) — Google Display only — defaults to headline if omitted. On LinkedIn, reused as the optional secondary description text on traffic (link) ads; omitted if not provided.
  • body (string) — Required on legacy + attach shapes. For X/Twitter this is the tweet text (max 280 chars including a ~24-char URL when linkUrl is set). On LinkedIn this is the post commentary (the intro text shown a...
  • callToAction (string) — Required on legacy + attach shapes for Meta. Honoured on TikTok (passes through to the Spark Ad creative's call_to_action) and on LinkedIn (the CTA button on the ad; defaults to LEARN_MORE when `lin...
  • linkUrl (string) — Required on legacy + attach shapes (skip for multi-creative). On LinkedIn it's the ad's destination URL; required for traffic ads, optional for engagement / awareness.
  • imageUrl (string) — Image creative for Meta/Google/Pinterest/LinkedIn on legacy + attach shapes (mutually exclusive with video). Required for LinkedIn ads unless video is set. Not required for Google Search campaigns...
  • images (object) — Google Display (Responsive Display Ads) only. Google RDA requires both a landscape (1.91:1) and a square (1:1) marketing image; sending only one is rejected upstream as 'Too few.' (NOT_ENOUGH_*_MARKET...
  • video (object) — Meta (facebook, instagram) and LinkedIn. When set, creates a VIDEO ad on the legacy (or, for Meta, attach) shape. Mutually exclusive with imageUrl. For Meta multi-creative, set video per entry ins...
  • creatives (array) — Meta-only. When present, switches to the multi-creative shape: creates 1 campaign + 1 ad set + N ads (one per entry here). Top-level headline / body / imageUrl / linkUrl / callToAction are i...
  • adSetId (string) — Meta-only. When present, switches to the attach shape: adds one new ad to this existing ad set without creating a new campaign. Budget, targeting, goal, schedule, AND bid strategy are inherited from t...
  • businessName (string) — Google Display only
  • boardId (string) — Pinterest only. Board ID (auto-creates if not provided).
  • organizationId (string) — LinkedIn only. The Company Page that authors the Direct Sponsored Content ("dark") post backing the ad — accepts a numeric organization ID or a full urn:li:organization:N URN. Required unless the re...
  • countries (array) — ISO 3166-1 alpha-2 country codes (e.g. ['NL']). Defaults to ['US'] when no cities or regions are provided. (LinkedIn currently honours country-level targeting only.)
  • cities (array) — Meta-only. City-level geo targeting. Each city is targeted by Meta's opaque key (the city ID) which can be looked up via GET /v1/ads/targeting/search?type=city&q=<name>&country_code=<ISO>. Optiona...
  • regions (array) — Meta-only. Region-level (state/province) geo targeting. Each region is targeted by Meta's opaque key (the region ID) which can be looked up via `GET /v1/ads/targeting/search?type=region&q=<name>&cou...
  • ageMin (integer)
  • ageMax (integer)
  • interests (array) — Interest objects from /v1/ads/interests. Each must include id and name.
  • endDate (string) — Required for lifetime budgets
  • audienceId (string) — Custom audience ID for targeting
  • campaignType (string) (enum: display, search) — Google only
  • keywords (array) — Google Search only
  • additionalHeadlines (array) — Google Search RSA only. Extra headlines.
  • additionalDescriptions (array) — Google Search RSA only. Extra descriptions.
  • advantageAudience (integer) (enum: 0, 1) — Meta only. Controls the Advantage audience feature (targeting_automation). 0 = disabled (default), 1 = enabled. Meta Marketing API requires this field on all ad set creation requests.
  • attributionSpec (array) — Meta only. Conversion attribution window for the ad set — maps 1:1 to Meta's ad-set attribution_spec. Only honored for conversion goals (conversions, lead_generation, app_promotion); ignored f...
  • gender (string) (enum: all, male, female) — Meta only. Restrict the audience by gender. 'male' targets men only, 'female' targets women only, 'all' (default) targets everyone. Ignored by non-Meta platforms.
  • bidStrategy (any) — Meta bid strategy applied to the ad set.
  • bidAmount (number) — 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.
  • roasAverageFloor (number) — 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.
  • dsaBeneficiary (string) — Name of the legal entity benefiting from the ad. Required by Meta when targeting EU users (DSA Article 26). Not enforced at schema level; enforced server-side when targeting intersects EU member state...
  • dsaPayor (string) — Name of the legal entity paying for the ad. Required by Meta when targeting EU users (DSA Article 26). Note Meta API spelling: dsa_payor (not dsa_payer).
  • brandIdentity (object) — TikTok only. Synthetic Brand Identity used when the ad attributes to a CUSTOMIZED_USER (instead of a real TT_USER @username). Required on the FIRST CUSTOMIZED_USER ad on a tiktokads SocialAccount wi...
  • identityType (string) (enum: TT_USER, CUSTOMIZED_USER) — TikTok only. Forces the identity attribution on the ad: - TT_USER: the posting account's open_id (real @username branding). Requires a connected TikTok posting account on the same profile...
  • promotedObject (object) — What the ad optimises against. Behaviour depends on the platform. Meta: forwarded to the ad set's promoted_object (snake-cased). Required for goals whose ad-set optimization_goal points at a sp...

Responses ​

201 — Ad(s) created

one of:

    • ad ($ref)
  • message (string)
    • ads (array)
  • platformCampaignId (string)
  • platformAdSetId (string)
  • message (string)

400 — Missing required fields, invalid values, or non-Meta platform used with creatives[] / adSetId

401

403 — Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

422 — Platform ads connection required (TikTok Ads, X Ads) or missing linked account