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

FieldTypeRequiredDescription
namestringYesThe ad's name, and that of the levels that don't have one.
statusstringNoThe tree's intended final state (active or paused).
campaignobjectNo{"id": ...} for an existing campaign; without id, describes the one that would be created.
adsetobjectYes{"id": ...} for an existing ad set; without id, describes the one that would be created.
ad.formatstringYesimage or video.
ad.link_urlstringYesThe ad's destination URL.
ad.mediaarrayYesThe creative's file(s), by url, hash or id. Meta Ads only.
ad.facebook_ads.page_idstringYesThe page that publishes the ad. Must belong to the connection's account. Meta Ads only.
integration_dry_runNoIn 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.

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.