Ads

Create a campaign on Meta Ads, Google Ads and TikTok Ads via API

One call creates the campaign in the ad account your client connected, with no Meta API integration to build and no app review. You describe objective and budget in a single vocabulary and Connect handles the token and the translation. The campaign is created paused, so nothing spends until you activate it. On Google Ads, the same route creates Demand Gen and Performance Max campaigns, with a daily budget and a bidding strategy. On TikTok Ads, the route creates Traffic, Reach and Video views campaigns, with an optional daily or lifetime budget: with it, the campaign shares the budget among its ad groups (CBO); without it, each ad group carries its own.

The request

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

{
  "name": "Black Friday",
  "budget": {
    "amount": 50,
    "type": "daily"
  },
  "facebook_ads": {
    "objective": "traffic",
    "special_ad_categories": []
  }
}

What you can do

  • Pick the objective: awareness, traffic, engagement, leads, app_promotion or sales.
  • Set the budget on the campaign (CBO) or leave it to each ad set (ABO).
  • Use a daily or lifetime budget, in the client account's currency.
  • Send special_ad_categories for credit, employment, housing and politics.
  • Set a spending limit with facebook_ads.spend_cap.
  • Read the accepted values from GET /ads/options?integration_slug=facebook_ads.
  • On Google Ads, create a Demand Gen or Performance Max campaign with google_adwords.type and its own daily budget.
  • On Google Ads, pick the bidding in google_adwords.bidding: maximize_conversions, with an optional target_cpa, or maximize_conversion_value, with an optional target_roas.
  • On Google Ads, list the account's enabled conversion actions with GET /ads/google_adwords/conversion-actions; bidding optimizes for the ones with primary_for_goal.
  • On TikTok Ads, create a Traffic, Reach or Video views campaign with tiktok_ads.objective: traffic, reach or video_views.

Rules and limits

  • Without status, the campaign is created paused.
  • Idempotency-Key is required in the header. Repeating the call with the same key and the same body returns 200 with Idempotent-Replay: true and does not create another campaign.
  • The budget sits on the campaign (CBO) or on each ad set (ABO), never on both. There is no level field: the level is where the budget is.
  • budget.amount is in the account's currency, never in cents.
  • facebook_ads.objective is required and can't be changed after creation.
  • The response is synchronous: 201 with the created campaign. Reusing the key with a different body returns 422 idempotency_key_reused.
  • On Google Ads, budget is required and daily only: the budget always lives on the campaign. facebook_ads is refused.
  • On TikTok Ads, tiktok_ads.objective is traffic, reach or video_views, and budget is optional on the campaign, daily or lifetime: with it, the campaign shares the budget among its ad groups (CBO), which take no budget; lifetime needs schedule.end on the ad group. facebook_ads is refused too.

Main fields

FieldTypeRequiredDescription
namestringYesCampaign name.
statusstringNoactive or paused. Without it, the campaign is created paused.
budget.amountnumberYesAmount in the ad account's currency, never in cents. Sending the budget here makes the campaign CBO.
budget.typestringNodaily or lifetime. lifetime requires schedule.end on the ad set.
facebook_ads.objectivestringYesawareness, traffic, engagement, leads, app_promotion or sales. Required on create and can't be changed afterwards. Meta Ads only.
facebook_ads.special_ad_categoriesarrayNoRequired for credit, employment, housing and politics.
facebook_ads.spend_capnumberNoThe campaign's spending limit, in the account's currency. null removes it.
google_adwords.typestringNoGoogle Ads: demand_gen or performance_max. Required on Google.
google_adwords.biddingobjectNoGoogle Ads: strategy (maximize_conversions, the default, or maximize_conversion_value) and, optionally, target_cpa or target_roas (4 means 400%).
tiktok_ads.objectiveNoTikTok Ads: traffic, reach or video_views. Required on TikTok; the campaign budget is optional (CBO).

Who it is for

  • Ads platform for small businesses

    The end client fills in objective and budget in your product and you create the campaign in their account, without building an OAuth flow with Meta.

  • Agency with its own dashboard

    Create standardized campaigns for many clients from a template, changing only name, objective and budget.

  • Paid media AI agent

    The agent reads the vocabulary in GET /ads/options, builds the campaign and leaves it paused for a human to review before activating.

Works with

  • Meta Ads
  • Google Ads
  • TikTok Ads

Frequently asked questions

Does the campaign start spending as soon as it is created?

No. Without status it is created paused. You activate it when you want with PATCH /ads/campaigns/{id} and status active.

Can I retry the call without creating a duplicate campaign?

Yes. Always send the same Idempotency-Key. If the first call succeeded, the retry returns the same response with Idempotent-Replay: true.

Should the budget go on the campaign or on the ad set?

On one of them. With budget on the campaign it is CBO; without it, each ad set carries its own (ABO). Sending it to the wrong level returns 409 budget_level_mismatch.

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.