Meta Ads
Create, boost, measure and manage Facebook + Instagram ads with Zernio API
Quick Reference
| Property | Value |
|---|---|
| Hierarchy | Campaign → Ad Set → Ad (created in one call, or level by level) |
| Goals (`goal`) | 9: engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales |
| Buying types | AUCTION (default) and RESERVED (see Reach & Frequency) |
| Budget levels | CBO (campaign) and ABO (ad set), routed automatically on reads |
| Bid strategies | LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS |
| Creative formats | Single image, video, carousel (2-10 cards), dynamic creative, per-placement assets, catalog, instant form, messaging, call (see Creatives) |
| Call to action values | 27 |
| Special ad categories | HOUSING, EMPLOYMENT, CREDIT, ISSUES_ELECTIONS_POLITICS, FINANCIAL_PRODUCTS_SERVICES, ONLINE_GAMBLING_AND_GAMING |
| Image formats | JPEG, PNG (public URL or base64), max 30 MB |
| Video formats | MP4, MOV, max 4 GB |
| Ad previews | Yes, Meta iframe HTML for ~60 formats, before or after create (see Previews) |
| Dry-run validation | Yes, `validateOnly: true` validates the whole tree and creates nothing |
| Insights | Cached rollups on /ads/tree plus raw Graph passthrough and async reports (see Insights) |
| Audiences | Customer list, website, lookalike, engagement, saved targeting |
| Conversions API | Yes, with hashed PII, dedup, Event Match Quality read-back and Limited Data Use |
| Lead forms | Yes, forms + leads via webhook or polling |
| Scheduling | Yes, ad set start/end dates (editable after launch) |
| Analytics | Yes |
Before You Start
Meta ads run on a connected Facebook account with the ads scopes granted, plus an ad account the connected user can act on.
Requirements:
- A Meta Business account (business.facebook.com) with at least one ad account (
act_<n>) - A Facebook Page (ads are published as the Page; Instagram placements need an IG professional account linked to that Page)
- An Instagram-only connection is not enough: Instagram Login can't grant ads scopes, so a
facebook(ormetaads) connection must exist in the same profile. Without one, ads calls on an InstagramaccountIdreturn422 linked_account_required - The ads scopes on the connection (see OAuth Scopes). Accounts connected before the Ads add-on was enabled must reconnect
- A Pixel or dataset for any conversion-optimized goal (see Conversion campaigns)
- Meta reviews every ad. A successful create means the ad exists, not that it is delivering: watch
reviewStatus, which is distinct fromstatus
OAuth Scopes
Meta ads run on the token of a connected Facebook account. Workspaces with the Ads add-on request these additional scopes during the standard Facebook connect flow:
| Scope | What it enables |
|---|---|
ads_management | Create and manage campaigns, ad sets, ads, creatives, audiences, pixels, and reservations |
ads_read | Read ad accounts and insights |
pages_manage_ads | Create, list and archive lead forms on the Page |
leads_retrieval | Read submitted leads from lead ads |
ads_management covers the whole surface documented here, including Reach & Frequency and the Business Manager portfolio list. Nothing on this page needs business_management.
Instagram Login can't grant ads scopes, so ads owned by Instagram accounts are managed with the token of a Facebook account connected in the same profile.
Accounts connected before the Ads add-on was enabled won't have these scopes; reconnect the account to pick them up. Account Health shows what a connected account was actually granted.
The campaign tree
Every Meta ad lives in a three-level tree, and each level owns different settings. That split is what decides which endpoint you call:
| Level | Owns | Where it's documented |
|---|---|---|
| Campaign | Objective (goal), bid strategy, spend cap, the budget on CBO campaigns | Campaigns |
| Ad set | Targeting, schedule, optimization goal, promotedObject, the budget on ABO campaigns | Ad Sets |
| Ad | The creative: headline, body, media, CTA, link | Creatives |
You rarely build the tree level by level: POST /v1/ads/create creates all three in one call, POST /v1/ads/boost wraps an existing organic post the same way, and GET /v1/ads/tree reads the whole hierarchy back, nested with rolled-up metrics. Whether the budget lives on the campaign (CBO) or the ad set (ABO) decides which update endpoint accepts it, see budget routing.
In This Section
Campaigns
Create standalone campaigns, bid strategy, ROAS, and the campaign tree
Ad Sets
Budgets, schedule, optimization goal, and post-launch delivery edits
Creatives
Video, carousel, per-placement assets, and Advantage+ enhancements
Creative Library
Standalone creatives and the ad image library
Previews
Render an ad or a draft creative as Meta renders it
Targeting
Interest, demographic, geo, and placement targeting
Custom Audiences
Customer list, website, lookalike, and engagement audiences
Boost a Post
Turn an existing organic post into a paid ad
Creative Testing
Run multi-creative campaigns to test variations
Conversion Campaigns
Conversion goals and promoted objects
Catalog Ads
Advantage+ catalog ads from a product set
Messaging & Call Ads
Ads that open WhatsApp, Messenger, Instagram Direct, or dial a number
Click-to-WhatsApp Ads
The original CTWA endpoint (superseded by Messaging Ads)
Lead Gen Forms
Create instant forms and retrieve leads
Reach & Frequency
Quote, reserve, and buy fixed-price reserved campaigns
Insights
Rolled-up metrics, raw Graph queries, and async reports
Meta Pixels
Create and manage Meta Pixels
Conversions API
Send server-side conversion events, with consent handling
Ad URL Tracking Tags
Attach click-URL tracking parameters to ads
Duplicate & Lifecycle
Duplicate, pause, resume, delete, and dry-run before you spend
Account & Ops Reads
Change log, studies, finances, labels, budget schedules, portfolios
Ad Comments
Read and manage comments on your Meta ads
Media & Limits
Media requirements, what you can't do, and common Meta errors
Related Endpoints
- Create Standalone Ad - Build campaign, ad set, and ad in one call
- Boost Post - Promote an existing organic post
- Ad Tree - Nested hierarchy with rolled-up metrics
- Query Ad Insights - Raw Graph insights passthrough
- List Ad Accounts - Ad accounts a connection can reach
- Ad Audiences - Custom and lookalike audiences
- Ad Creatives - Standalone creative library
- Lead Forms and Leads - Instant forms and submissions
- Tracking Tags - Pixels and click-URL parameters
- Send Conversions - Server-side conversion events