Ads

Pozy runs paid campaigns on nine ad networks through one set of /v1/ads endpoints. You connect an ad account once, then create campaigns, boost posts, build audiences, send conversions and read spend with the same request shapes everywhere. Each network keeps its own rules, and the pages in this section say where they differ.

#Supported networks

An ad connection is its own connected account with its own accountId. It sits in a profile next to the posting accounts, and it counts once toward pricing however many ad accounts it can reach.

#How the pieces fit

Every network nests ads in three levels. Pozy uses the same three names for all of them, and maps each one to the network's own object.

A few more objects show up around them:

• Ad account (adAccountId): the account the network bills, such as act_1234567890 on Meta or a customer id on Google. One connection can reach many.
• Creative: the headline, body, media, call to action and link. On Meta you can build one on its own and reuse it with existingCreativeId.
• Audience: a list of people you upload or a segment the network builds for you. See Audiences.

POST /v1/ads/create builds the whole tree in one call. POST /v1/ads/boost wraps an organic post in the same tree. GET /v1/ads/tree reads it back with metrics rolled up per level.

#Connect an ad account

curl "https://api.pozy.ai/v1/connect/googleads/ads?profileId=66b2e19d8c3f5a7e9d0b1c2a&redirect_url=https://app.example.com/ads/connected" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/connect/googleads/ads?profileId=66b2e19d8c3f5a7e9d0b1c2a&redirect_url=https:%2F%2Fapp.example.com%2Fads%2Fconnected", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
// data.authUrl the first time, data.alreadyConnected + data.accountId afterwards

import os, requests

resp = requests.get(
    "https://api.pozy.ai/v1/connect/googleads/ads",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={"profileId": "66b2e19d8c3f5a7e9d0b1c2a", "redirect_url": "https://app.example.com/ads/connected"},
)
print(resp.json())

adAccountId or adAccountIds on the connect call limit the sync to the ad accounts you name. The full flow, with hosted and headless options, is in Connecting accounts.

#What each network supports

A field a network cannot honor is rejected at create time with a 400 that names it. Pozy never drops a field quietly.

#Money and units

• Budgets and bids are whole units of the ad account's currency: 75 on a USD account is $75.00. Never cents, never micros.
• Each campaign node reports its currency. Pozy never converts between currencies, so do not add spend across ad accounts that bill differently.
• Raw reports from a network (Google GAQL rows, Keyword Planner, Meta live insights) keep that network's units. Google's micros, for example, divide by 1,000,000.

#Reviews and statuses

Every network reviews ads before they deliver. A successful create means the ad exists, not that it runs. Each ad carries three separate fields:

status inherits from parents: an active ad under a paused campaign reads paused. Deleted ads stay in the tree as cancelled, so their past spend keeps counting.

#Retries

Ad creates and boosts are not idempotent on the networks' side. A blind retry after a timeout can launch a second campaign that spends. Send an Idempotency-Key header on every create, boost and duplicate, and reuse it on retries. See Idempotency.

#Pricing

Managed ads bill per active ad per month. The first 500 active ads in a workspace are free, then each costs $0.01 per month. Only ads that are running or in review count: paused, ended, rejected and deleted ads do not, and the count is metered daily, so pausing a campaign takes its ads off the meter the same day. There is no percentage of ad spend. The spend itself is billed by the network to the ad account's own payment method.

See Pricing for every other meter and how they roll up on one invoice.

#Webhook events

Subscribe to these to react to reviews, delivery problems, budgets and new leads without polling. Payloads are in the events reference.

#Endpoints

The ads surface is large. These are the calls most integrations start with; each network page lists its own.

The full list, grouped by tag, is in the API reference.