Meta Ads

Meta Ads covers Facebook, Instagram, Messenger, Threads, Audience Network and WhatsApp Status placements. It is the most complete network in Pozy: every operation in the ads overview works here, plus several that only Meta offers.

#Before you start

On Meta's side you need:

• A Business portfolio with at least one ad account (act_<number>). You can also create one through the API.
• A Facebook Page. Ads run as the Page. Instagram placements also need an Instagram professional account linked to that Page.
• A pixel or dataset if the campaign optimizes for conversions. See Pixels and tags.

#Connect

Call GET /v1/connect/facebook/ads (or /v1/connect/instagram/ads) with the profileId. Meta offers two login modes, picked with loginMode:

Either way, ads need a Page as the actor. With business login, pass pageId on the connect call or change the default Page later with PUT /v1/accounts/{accountId}/facebook-page.

A metaads account is for ads only. Page and Instagram insights need the organic Facebook or Instagram connection, which is a separate connected account.

#Create an ad account

POST /v1/ads/accounts creates a Meta ad account inside the customer's own Business portfolio. Find the portfolio with GET /v1/ads/businesses, then send accountId (an active metaads connection), businessId, name, currency and timezoneId. timezoneId is Meta's numeric timezone id, not an IANA name. The connection needs Business admin access.

#Create a campaign

POST /v1/ads/create builds a campaign, an ad set and an ad in one call. Every field sits at the top level, and the network is inferred from accountId.

curl -X POST https://api.pozy.ai/v1/ads/create \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: spring-sale-us-feed" \
  -d '{
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "adAccountId": "act_1234567890",
    "name": "Spring sale - US",
    "goal": "traffic",
    "budgetAmount": 40,
    "budgetType": "daily",
    "status": "PAUSED",
    "headline": "30% off everything this week",
    "body": "Free shipping on orders over $50.",
    "imageUrl": "https://cdn.example.com/spring-1080.jpg",
    "linkUrl": "https://shop.example.com/spring",
    "callToAction": "SHOP_NOW",
    "countries": ["US"],
    "ageMin": 25,
    "ageMax": 54
  }'

const res = await fetch("https://api.pozy.ai/v1/ads/create", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Idempotency-Key": "spring-sale-us-feed",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    accountId: "66b2e19d8c3f5a7e9d0b1c2d",
    adAccountId: "act_1234567890",
    name: "Spring sale - US",
    goal: "traffic",
    budgetAmount: 40,
    budgetType: "daily",
    status: "PAUSED",
    headline: "30% off everything this week",
    body: "Free shipping on orders over $50.",
    imageUrl: "https://cdn.example.com/spring-1080.jpg",
    linkUrl: "https://shop.example.com/spring",
    callToAction: "SHOP_NOW",
    countries: ["US"],
    ageMin: 25,
    ageMax: 54,
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.ad.platformCampaignId, data.ad.reviewStatus);

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/ads/create",
    headers={
        "Authorization": f"Bearer {os.environ['POZY_API_KEY']}",
        "Idempotency-Key": "spring-sale-us-feed",
    },
    json={
        "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
        "adAccountId": "act_1234567890",
        "name": "Spring sale - US",
        "goal": "traffic",
        "budgetAmount": 40,
        "budgetType": "daily",
        "status": "PAUSED",
        "headline": "30% off everything this week",
        "body": "Free shipping on orders over $50.",
        "imageUrl": "https://cdn.example.com/spring-1080.jpg",
        "linkUrl": "https://shop.example.com/spring",
        "callToAction": "SHOP_NOW",
        "countries": ["US"],
        "ageMin": 25,
        "ageMax": 54,
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["ad"]["_id"])

{
  "ad": {
    "_id": "66d4a1b2c3e4f5a6b7c8d9e2",
    "name": "Spring sale - US",
    "platform": "facebook",
    "status": "paused",
    "configuredStatus": "PAUSED",
    "reviewStatus": "in_review",
    "adType": "standalone",
    "goal": "traffic",
    "budget": { "amount": 40, "type": "daily" },
    "platformAdAccountId": "act_1234567890",
    "platformCampaignId": "120250000000000000",
    "platformAdSetId": "120250000000000001",
    "platformAdId": "120260000000000000",
    "creative": { "creativeId": "120250000000000005", "pageId": "811889972008357" }
  },
  "message": "Ad created"
}

Keep three ids from the response: _id for per-ad calls, platformCampaignId for campaign calls and platformAdSetId for ad set calls. creative.creativeId can be reused later as existingCreativeId.

Without status: "PAUSED" the ad is created active and goes straight into Meta's review. To provision a campaign container first and add ad sets to it later, use POST /v1/ads/campaigns, then pass the campaign id as existingCampaignId on each create. POST /v1/ads/campaigns creates the campaign paused unless you send status: "ACTIVE".

#Check a request without spending

Add validateOnly: true to run the whole tree through Meta's own validator. Nothing is created. You get 200 with one result per node (validated or skipped) and Meta's error verbatim when something is wrong. Meta can only validate an ad set against a real campaign, so on a fresh tree the ad set reports skipped unless you pass existingCampaignId. Dry runs work on the single-ad shape only, not with creatives[], adSetId or reserved buying.

#Goals

goal picks the Meta objective and a sensible optimization goal for it.

optimizationGoal, billingEvent and promotedObject override the defaults when you need Meta's exact vocabulary (for example LINK_CLICKS or OFFSITE_CONVERSIONS).

#Budgets and bidding

Bid strategies go inside platformSpecificData on create:

platformSpecificData also takes dailyMinSpendTarget and lifetimeMinSpendTarget (reserve part of a campaign budget for one ad set), customerLifecycle (new customers only, or all) and adSchedule (dayparting rows of dayOfWeek, startHour, endHour, which need a lifetime budget).

Budget schedules raise a budget for a sale or a busy weekend: POST /v1/ads/high-demand-periods with exactly one of campaignId or adSetId, and GET /v1/ads/high-demand-periods to read them.

Value rule sets raise or lower the bid for segments worth more or less to you, without splitting them into separate ad sets. Create one with POST /v1/ads/value-rule-sets, then attach it with valueRuleSetId on the create or on PUT /v1/ads/ad-sets/{adSetId}. Meta allows 6 sets per ad account, 10 rules per set and 4 criteria per rule. An update replaces the whole set, so read it first and send every rule you want to keep.

#Creatives and formats

Exactly one media source per creative. Pick the shape:

callToAction takes the values listed in the API reference, such as SHOP_NOW, LEARN_MORE, SIGN_UP and CONTACT_US. Media URLs must be public: Meta downloads them itself, and a hotlink-protected host fails.

#Advantage+ options

• creativeFeatures opts a creative in or out of Meta's individual Advantage+ creative enhancements, keyed by Meta's feature names. Anything you leave out is opted out.
• advantageAudience: 1 lets Meta expand delivery beyond your targeting. Pozy sends 0 for you unless you set it.
• budgetLevel: "campaign" turns on Advantage campaign budget.
• promotion attaches an offer (PERCENTAGE_OFF, AMOUNT_OFF, FREE_SHIPPING, FREE_RETURN, PROMO_CODE) to the creative. Check ad.creative.promotionStatus on a later read to see whether Meta kept it.

#Conversation and call ads

POST /v1/ads/messaging creates an ad that opens a chat instead of a web page. destination picks where:

The ad set is built with conversation optimization and the matching destination type. Useful extras:

• welcomeMessage replaces Meta's greeting and pre-fills the person's first message.
• workflowId starts one of your workflows in the conversation the click opens.
• existingPostId or objectStoryId runs an organic post as the ad instead of a new creative.
• adSetId adds creatives to a running conversation ad set without resetting its learning.

POST /v1/ads/call builds a call ad that dials phoneNumber (E.164). linkUrl must be a real web page, not a tel: link. POST /v1/ads/ctwa is the older click-to-WhatsApp endpoint; it still works, but new code should use /v1/ads/messaging with destination: "whatsapp".

#Creative testing

Send creatives[] instead of the single-creative fields to get one campaign, one ad set and N ads that share the budget. The ads are named <name> #1, <name> #2 and so on, and the response returns ads[] instead of ad. To add a variation later, call the create again with the ad set's id in adSetId and a single creative: it inherits the budget, targeting and schedule and keeps the learning Meta has done.

Rank variations with the per-ad metrics on GET /v1/ads/tree, or split one ad's results by the asset Meta served with the breakdowns image_asset, video_asset, body_asset and title_asset.

GET /v1/ads/studies lists the A/B tests and lift studies on the ad account.

#Partnership ads

Partnership ads run a creator's Instagram post under your ad account, with both handles on the ad. Ask a creator for permission with POST /v1/ads/partnership-permissions, track who has granted it with GET /v1/ads/partnership-permissions, and find their eligible posts with GET /v1/ads/partnership-content. This is in private beta, so the calls can return feature_not_available until it opens to your workspace.

#Reach and frequency

Reach and frequency buys lock a price for a fixed audience and frequency before you spend.

#Previews

GET /v1/ads/{adId}/preview?formats=INSTAGRAM_STORY,MOBILE_FEED_STANDARD renders an existing ad. POST /v1/ads/preview renders a creative before it is on an ad, from existingCreativeId or a raw creativeSpec. Both return Meta's iframe HTML, one per format, up to 10 formats per call. Embed the snippet as it is and fetch it when the user opens the preview: the signed URL inside is short-lived.

#Ad comments

GET /v1/ads/{adId}/comments reads the comments on an ad, including dark posts that never appeared on the Page. An ad that runs on both Facebook and Instagram has two threads: pick one with placement=facebook or placement=instagram. Reply through the normal comments endpoints with the post id the response returns in meta.effectiveStoryId. Hiding and deleting through the ad endpoints is TikTok only and returns 501 on Meta.

#Manage running ads

Each switch is independent. Pausing a campaign stops everything under it, but resuming it only restarts children whose own switch is on. When a status is already what you asked for, nothing is written and the response says skipped: 1.

Duplicates default to a deep copy created paused (statusOption: "PAUSED"), so nothing spends until you activate it. renameStrategy, renamePrefix and renameSuffix name the copies, and the response maps each source id to its copy in adSetIdMap and adIdMap. A large campaign takes minutes because Meta copies one object at a time.

GET /v1/ads/ad-sets/{adSetId} reads the ad set live from Meta, including learning_stage_info.status (LEARNING, SUCCESS, FAIL, WAIVING). A missing status means unknown, not "out of learning".

#Reporting

Breakdown dimensions: age, gender, country, region, publisher_platform, platform_position, device_platform, impression_device, image_asset, video_asset, body_asset, title_asset.

Metrics on each node include spend, impressions, reach, clicks, ctr, cpc, cpm, conversions, actions, actionValues, purchaseValue and roas. Reach is de-duplicated within a day only, so never sum it across days. A freshly connected ad account can answer 202 with backfillPending: true while history loads: retry after the Retry-After delay.

When polling an async report, stop on Job Completed, Job Failed or Job Skipped. Start at 5 seconds and back off to a minute. More in Reporting.

#Regulated ads

• specialAdCategories declares housing, employment, credit, financial products, politics or gambling ads. Meta then restricts targeting (no income or ZIP targeting).
• Ads delivered in the EU need dsaBeneficiary and dsaPayor unless the ad account has defaults (GET /v1/ads/dsa-defaults).
• Other regimes (Brazil, Thailand, India and more) use regionalRegulatedCategories and regionalRegulationIdentities.

#Limits and errors

Locations overlap is the most common targeting error: do not send a city together with the country that contains it. See Targeting.

#Endpoints

Campaigns, ad sets, ads and reporting:

Meta-only tools:

Conversation ads and reach and frequency: