Ads
Create an ad set or ad group on Meta, Google and TikTok Ads via API
Create the ad set inside an existing campaign, in the account your client connected: audience, schedule, placements, optimization goal and bid. Fields common to any platform sit at the top level and what is specific to Meta goes in the facebook_ads block. No app review and no token handling. On Google Ads, the same route creates an ad group in a Demand Gen campaign. On TikTok Ads, it creates an ad group in a Traffic, Reach or Video views campaign, with a daily or lifetime budget, location, audience and schedule.
The request
POST /api/ads/adsets?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"campaign_id": "120250000000000001",
"name": "BR 25-45",
"budget": {
"amount": 20,
"type": "daily"
},
"targeting": {
"countries": [
"BR"
],
"age_min": 25,
"age_max": 45
},
"facebook_ads": {
"optimization_goal": "link_clicks",
"billing_event": "impressions"
}
}What you can do
- Target by countries, age (age_min and age_max) and genders.
- Target by interests and custom audiences, including exclusions, in facebook_ads.targeting.
- Set a schedule with schedule.start and schedule.end.
- Choose placements with facebook_ads.placements.
- Choose a bid with bid_strategy (lowest_cost, bid_cap, cost_cap) and bid_amount.
- Send promoted_object, destination_type and attribution_spec on create.
- On Google Ads, create an ad group in a Demand Gen campaign with just campaign_id, name and status.
- On TikTok Ads, create an ad group in a Traffic, Reach or Video views campaign, with location, age, gender, audiences, schedule and optimization goal.
Rules and limits
- Idempotency-Key is required in the header; repeating with the same key returns 200 with Idempotent-Replay: true.
- Without status, the ad set is created paused.
- The budget sits on the campaign (CBO) or on the ad set (ABO), never on both. A budget on an ad set of a CBO campaign returns 409 budget_level_mismatch.
- budget.type lifetime requires schedule.end.
- facebook_ads.optimization_goal and facebook_ads.billing_event are required; accepted values are in GET /ads/options.
- promoted_object (pixel, page or custom conversion) must belong to the connection's account, and applies on create only.
- bid_amount requires bid_strategy.
- On Google Ads, budget, schedule, targeting and facebook_ads are refused: the budget lives on the campaign. Under a Performance Max campaign the route answers 422 ads_unsupported_operation, and the asset group is created with its assets through POST /ads.
- On TikTok Ads, targeting.countries or tiktok_ads.location_ids is required, and facebook_ads is refused. If the campaign shares its budget (CBO), the ad group takes no budget; without CBO, budget is required, daily or lifetime, and lifetime needs schedule.end. Under a CBO campaign, a budget on the ad group answers 409 budget_level_mismatch. Age, gender, tiktok_ads.audience_ids and schedule are optional; without schedule.start, it starts now. The goal comes from tiktok_ads.optimization_goal and the bid from tiktok_ads.bid_strategy (lowest_cost or cost_cap with bid_amount); tiktok_ads.frequency applies on Reach only. The ad group runs on the TikTok placement only. Under a campaign with another objective, the route answers 422 ads_unsupported_operation.
Main fields
| Field | Type | Required | Description |
|---|---|---|---|
| campaign_id | string | Yes | The campaign, by its id or by the Connect uuid. |
| name | string | Yes | Ad set name. |
| budget.amount | number | No | Ad set budget (ABO), in the account's currency. Only valid when the campaign has no budget. |
| schedule.end | string | No | End date. Required when budget.type is lifetime. |
| targeting.countries | array | Yes | Audience countries, for example ["BR"]. The rest of the targeting goes in facebook_ads.targeting. |
| facebook_ads.optimization_goal | string | Yes | Optimization goal. Required on create; values in GET /ads/options. Meta Ads only. |
| facebook_ads.billing_event | string | Yes | Billing event. Required on create. Meta Ads only. |
| facebook_ads.bid_strategy | string | No | lowest_cost, bid_cap or cost_cap. |
| facebook_ads.bid_amount | number | No | Bid amount. Requires bid_strategy. |
| facebook_ads.targeting.interests | array | No | Audience interests, with id and name. |
| tiktok_ads.location_ids | No | On TikTok Ads: TikTok location ids (states and regions), from GET /ads/targeting/search (type geo). In the response, the ad group's countries come back here too, as location ids. |
Who it is for
Campaign builder inside your SaaS
Your product collects the audience (country, age, interests) in its own screen and creates the ad set in the client's account with one call.
Audience A/B tests
Create several ad sets in the same campaign, changing only the targeting, and compare performance afterwards.
AI agent that suggests audiences
The agent proposes the targeting, creates the ad set paused and hands it over for approval before activating.
Works with
Meta Ads
Google Ads
TikTok Ads
Frequently asked questions
Do I need to create the campaign first?
For this route, yes: campaign_id is required. To create campaign, ad set and ad at once, use POST /ads.
Where do I put the budget?
On the ad set only if the campaign has no budget (ABO). If the campaign has a budget (CBO), sending budget on the ad set returns 409 budget_level_mismatch.
How do I find valid optimization and billing values?
In GET /ads/options?integration_slug=facebook_ads. An invalid value returns 422 validation_error with supported_values.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
