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
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Campaign name. |
| status | string | No | active or paused. Without it, the campaign is created paused. |
| budget.amount | number | Yes | Amount in the ad account's currency, never in cents. Sending the budget here makes the campaign CBO. |
| budget.type | string | No | daily or lifetime. lifetime requires schedule.end on the ad set. |
| facebook_ads.objective | string | Yes | awareness, traffic, engagement, leads, app_promotion or sales. Required on create and can't be changed afterwards. Meta Ads only. |
| facebook_ads.special_ad_categories | array | No | Required for credit, employment, housing and politics. |
| facebook_ads.spend_cap | number | No | The campaign's spending limit, in the account's currency. null removes it. |
| google_adwords.type | string | No | Google Ads: demand_gen or performance_max. Required on Google. |
| google_adwords.bidding | object | No | Google Ads: strategy (maximize_conversions, the default, or maximize_conversion_value) and, optionally, target_cpa or target_roas (4 means 400%). |
| tiktok_ads.objective | No | TikTok 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.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
