Ads

Create an ad on Meta Ads, Google Ads and TikTok Ads via API

A single POST /ads creates the ad and, if you want, the campaign and ad set above it. Each level uses an existing one ({"id": ...}) or describes the new one. If something fails midway, what was created is undone, so nothing is left spending. On Google Ads, the same POST /ads creates Demand Gen ads and Performance Max asset groups. On TikTok Ads, it creates a video ad in a Traffic, Reach or Video views campaign.

The request

POST /api/ads?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>

{
  "name": "Black Friday, imagem",
  "status": "active",
  "campaign": {
    "name": "Black Friday",
    "budget": {
      "amount": 50,
      "type": "daily"
    },
    "facebook_ads": {
      "objective": "traffic",
      "special_ad_categories": []
    }
  },
  "adset": {
    "name": "BR 25-45",
    "schedule": {
      "start": "2026-11-20T00:00:00-03:00"
    },
    "targeting": {
      "countries": [
        "BR"
      ],
      "age_min": 25,
      "age_max": 45
    },
    "facebook_ads": {
      "optimization_goal": "link_clicks",
      "billing_event": "impressions",
      "placements": {
        "publisher_platforms": [
          "facebook",
          "instagram"
        ]
      },
      "targeting": {
        "interests": [
          {
            "id": "6003139266461",
            "name": "Moda"
          }
        ],
        "advantage_audience": false
      }
    }
  },
  "ad": {
    "format": "image",
    "headline": "Black Friday",
    "body": "Up to 50% off",
    "link_url": "https://loja.com/bf",
    "call_to_action": "shop_now",
    "media": [
      {
        "type": "image",
        "url": "https://cdn.loja.com/bf.jpg"
      }
    ],
    "facebook_ads": {
      "page_id": "1068595869664481"
    }
  }
}

What you can do

  • Create campaign, ad set and ad in one call.
  • Reuse an existing campaign or ad set by passing {"id": ...}.
  • Advertise an image (by url or hash) or a video (by url or id, with thumbnail_url).
  • Use two files of the same creative, one for the feed and one for stories and reels, with placements.
  • Set the page and Instagram account that publish the ad in the facebook_ads block.
  • Ask for status active to activate the tree at the end.
  • On Google Ads, create a Demand Gen ad, with a new or existing campaign and ad group.
  • On Google Ads, create a Performance Max asset group, or add assets to an existing one, with headlines, long headlines, descriptions, images, videos and logo in the google_adwords block.
  • On TikTok Ads, create a video ad with a cover, in a new or existing Traffic, Reach or Video views campaign and ad group, running as one of the TikTok accounts from GET /ads/tiktok_ads/identities.

Rules and limits

  • Everything is created paused. The requested status is applied in the last step, after the whole tree exists.
  • Idempotency-Key is required in the header. Repeating with the same key returns 200 with Idempotent-Replay: true.
  • If a creation step fails, what was created is undone in reverse order; what could not be undone comes in created. Repeating with the same key resumes where it stopped.
  • On activation, only the levels this call created are activated; levels referenced by id are not touched.
  • A video still processing returns 409 ads_video_not_ready. Repeat with the same key: the video and the levels already created are reused.
  • campaign is forbidden when adset.id is sent. The page must belong to the connection's account.
  • The response is synchronous: 201 with the result.
  • On Google Ads, images, videos and logos go in by the asset_id from POST /ads/google_adwords/media. A new campaign takes a daily budget and google_adwords.type: demand_gen or performance_max.
  • Performance Max has no ads: the asset group carries the creative, so the response is the ad set. A campaign that is neither Demand Gen nor Performance Max answers 422 ads_unsupported_operation.
  • On TikTok Ads, the ad is a video: ad.body (up to 100 characters), link_url, call_to_action and, in the tiktok_ads block, identity_id, identity_type, video_id and cover_image_id, the last two from POST /ads/tiktok_ads/media. A new campaign takes tiktok_ads.objective (traffic, reach or video_views) and, if you want, a budget, which it shares among its ad groups (CBO); without it, the new ad group takes a daily or lifetime budget. The new ad group also takes targeting.countries or tiktok_ads.location_ids. Before the first write, everything is checked in the account with reads only.

Main fields

FieldTypeRequiredDescription
namestringYesThe ad's name, and that of the created levels that don't have one.
statusstringNoThe tree's final state (active or paused). Everything is created paused and activation is the last step.
campaignobjectNo{"id": ...} uses an existing campaign; without id, describes the one to be created. Forbidden when adset.id is sent.
adsetobjectYes{"id": ...} uses an existing ad set; without id, describes the one to be created.
ad.formatstringYesimage or video.
ad.link_urlstringYesThe ad's destination URL.
ad.call_to_actionstringNoThe ad's button. Values in GET /ads/options.
ad.mediaarrayYesOne file for all placements, or two (feed and story versions) with placements. Image by url or hash; video by url or id. Meta Ads only.
ad.facebook_ads.page_idstringYesThe page that publishes the ad. Must be a page of the connection's account. Meta Ads only.
ad.facebook_ads.instagram_account_idstringNoThe Instagram account that publishes the ad.
campaign.google_adwords.typestringNoGoogle Ads, on a new campaign: demand_gen or performance_max. A daily budget goes with it.
ad.titlesarrayNoGoogle Ads: the headlines. Demand Gen, 1 to 5 of up to 40 characters; Performance Max, 3 to 15 of up to 30.
ad.google_adwords.imagesarrayNoGoogle Ads: the images, each with field (marketing, square, portrait, logo or landscape_logo) and asset_id.
campaign.tiktok_ads.objectiveNoTikTok Ads, on a new campaign: traffic, reach or video_views.
ad.bodyNoThe ad's main text. On TikTok Ads, up to 100 characters.
ad.tiktok_ads.identity_idNoTikTok Ads: the TikTok account the ad runs as, from GET /ads/tiktok_ads/identities, with its type in identity_type.
ad.tiktok_ads.video_idNoTikTok Ads: the video id from POST /ads/tiktok_ads/media, once ready.
ad.tiktok_ads.cover_image_idNoTikTok Ads: the cover's image_id, from POST /ads/tiktok_ads/media, in the video's aspect ratio.

Who it is for

  • Ad creator inside your product

    The client picks creative, copy and audience and you publish the complete ad in their account, without building Meta's OAuth flow.

  • Agency uploading creatives at scale

    Reuse an existing campaign and ad set and create dozens of new ads by changing only the media and the text.

  • AI agent that generates creatives

    The agent creates the ad paused, validates first with POST /ads/validate and only activates after approval.

Works with

  • Meta Ads
  • Google Ads
  • TikTok Ads

Frequently asked questions

Does the ad go live as soon as the call finishes?

Only if you send status active. Even then, everything is created paused and activation is the last step.

What if the call fails midway?

What was already created is undone and nothing is left spending. What could not be undone comes in created. Retrying with the same Idempotency-Key resumes where it stopped.

Does it work on Google Ads and TikTok Ads?

Yes, on Demand Gen and Performance Max campaigns. The body is the same POST /ads, with Google's fields in the google_adwords block. On Performance Max the response is the asset group, since it has no ads. On TikTok Ads, on Traffic, Reach and Video views campaigns with a video ad, with TikTok's fields in the tiktok_ads block.

Related

See everything you can do with Ads

See Connect applied to your product.

Try it for 15 days with no card, or walk our team through your use case.