Ads
Validate a Meta Ads, Google Ads or TikTok Ads ad without creating it via API
POST /ads/validate takes exactly the body of POST /ads and validates each level without creating anything in the client's account. You find field, page or media errors before wasting time and before any risk to the budget. On TikTok Ads, which has no dry run, Connect checks each level against the account with reads only.
The request
POST /api/ads/validate?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
{
"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
- Validate the whole tree (campaign, ad set and ad) before creating.
- Validate an ad over an existing campaign and ad set, by passing {"id": ...}.
- Get the result per level.
- Reuse the same body later in POST /ads, with no changes.
- Validate a Demand Gen ad or a Performance Max asset group on Google Ads, with the same body as POST /ads.
- Validate a video ad on TikTok Ads: the campaign and ad group named, objective, budget across levels, goal, countries, identity, video and cover.
Rules and limits
- Creates nothing in the client's account and records no operation.
- Does not need an Idempotency-Key.
- Each level is validated by the integration; levels that depend on a parent that doesn't exist yet come back as skipped.
- Field errors return 422 validation_error with errors and, for enums, supported_values.
- Uses only the connection in customer_integration, in the query, and checks that it belongs to the customer.
- On Google Ads the result comes per level, as on Meta Ads. Performance Max has no ad level: the asset group is the ad set.
- On TikTok Ads, every level comes back validated and the response carries integration_dry_run: false. What only creating reveals, such as a budget below TikTok's minimum, shows up on POST /ads.
Main fields
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | The ad's name, and that of the levels that don't have one. |
| status | string | No | The tree's intended final state (active or paused). |
| campaign | object | No | {"id": ...} for an existing campaign; without id, describes the one that would be created. |
| adset | object | Yes | {"id": ...} for an existing ad set; without id, describes the one that would be created. |
| ad.format | string | Yes | image or video. |
| ad.link_url | string | Yes | The ad's destination URL. |
| ad.media | array | Yes | The creative's file(s), by url, hash or id. Meta Ads only. |
| ad.facebook_ads.page_id | string | Yes | The page that publishes the ad. Must belong to the connection's account. Meta Ads only. |
| integration_dry_run | No | In the response, on TikTok Ads: false. TikTok has no dry run, and Connect checks each level with reads only. |
Who it is for
Form with instant feedback
Validate what the user filled in before they click publish and show the errors of each level on screen.
Batch approval
Validate hundreds of template-generated ads and create only the ones that passed.
Self-correcting AI agent
The agent builds the body, validates, reads the errors, fixes them and only then calls POST /ads.
Works with
Meta Ads
Google Ads
TikTok Ads
Frequently asked questions
Does validating spend budget or create objects?
No. The route creates nothing in the account and records no operation.
Is the body different from POST /ads?
No, it is the same body. You can validate and, if it passes, send it as is to POST /ads with an Idempotency-Key.
What does skipped mean in the result?
That level depends on a parent that doesn't exist yet, so it can't be validated on its own. On TikTok Ads there is no skipped: each level is checked against the account and comes back validated.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
