Targeting

Targeting tells a network who should see an ad. Pozy uses one set of field names across networks, then translates them into each network's own targeting spec. Portable fields such as countries, ageMin, ageMax, gender and languages work everywhere. The rest only mean something on the network they were looked up for, and a field a network cannot honor is rejected with a 400 that names it.

#Where targeting goes

#Look up ids

Cities, regions, interests, job titles and subreddits are ids that belong to each network. Find them with GET /v1/ads/targeting/search, using the accountId of the ad connection you will create the ad on.

curl -G https://api.pozy.ai/v1/ads/targeting/search \
  -H "Authorization: Bearer $POZY_API_KEY" \
  --data-urlencode "accountId=66b2e19d8c3f5a7e9d0b1c2d" \
  --data-urlencode "q=Amsterdam" \
  --data-urlencode "dimension=geo" \
  --data-urlencode "geoType=city" \
  --data-urlencode "countryCode=NL"

const res = await fetch("https://api.pozy.ai/v1/ads/targeting/search?accountId=66b2e19d8c3f5a7e9d0b1c2d&q=Amsterdam&dimension=geo&geoType=city&countryCode=NL", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
const cityKey = data.results[0].id; // send as { key: cityKey }

import os, requests

resp = requests.get(
    "https://api.pozy.ai/v1/ads/targeting/search",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={"accountId": "66b2e19d8c3f5a7e9d0b1c2d", "q": "Amsterdam", "dimension": "geo", "geoType": "city", "countryCode": "NL"},
)
print(resp.json()["results"][0])

{
  "results": [
    { "id": "2759794", "name": "Amsterdam", "type": "city", "path": ["Netherlands", "North Holland", "Amsterdam"], "audienceSize": null }
  ]
}

Send a geo result's id as key in cities, regions, zips or metros. A country result's id is the ISO code for countries. Interest and behavior results go in interests and behaviors as { id, name }.

geoType narrows geo searches to country, region, city (the default), subcity, neighborhood, place, zip, metro_area or geo_market. Google and LinkedIn ignore it and return every level, so filter on each result's type. GET /v1/ads/targeting/browse walks Meta's targeting category tree (by type and parentNodeId) instead of searching it. dimension defaults to interest. A dimension the network does not support returns 400 or 404.

#Estimate reach first

POST /v1/ads/targeting/reach-estimate returns an audience size range before you create anything:

{
  "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
  "adAccountId": "act_1234567890",
  "spec": { "countries": ["NL"], "ageMin": 25, "ageMax": 54, "interests": [{ "id": "6003107902433", "name": "Interior design" }] }
}

{ "available": true, "lower": 412000, "upper": 585000, "estimateReady": true }

estimateReady: false means the network is still computing, which happens with brand-new audiences: retry shortly. Networks without an estimate return available: false. On LinkedIn, bid pricing and supply forecasts add bid ranges and projected delivery.

#Meta

Housing, employment and credit ads (specialAdCategories) cannot use income or ZIP targeting. EU delivery needs dsaBeneficiary and dsaPayor.

#Google

locationTargetingType sets whether locations reach people physically there (presence) or also people interested in them (presence_or_interest, Google's default). Performance Max and Demand Gen take geo and language only. On a running campaign, PUT /v1/ads/campaigns/{campaignId}/targeting replaces devices (MOBILE, DESKTOP, TABLET, CONNECTED_TV, each with an optional bid modifier), locations, excludedLocations and languages.

#TikTok

PUT /v1/ads/{adId} with targeting is a partial update; fields you leave out keep their value, except that a new location replaces both location and ZIP targeting.

#LinkedIn

jobTitles cannot be combined with seniorities or jobFunctions. Cities, ZIP codes, radius and income return 400. Updates through PUT /v1/ads/{adId} merge facet by facet; send a facet empty to remove it.

#Pinterest

countries, regions, metros, zips, ageMin, ageMax, gender, languages, interests (from GET /v1/ads/interests) and customer list audiences. regions and zips cannot be combined. Targeting cannot change after create: recreate the ad.

#X

countries, regions, metros, cities, zips, interests, Tailored Audiences, gender and languages. Age rounds out to X's fixed ranges (starting at 13, 18, 21, 25, 35 or 50 and ending at 24, 34, 49 or 54, or open-ended), so ageMin: 20, ageMax: 40 targets 18 to 49. Income, custom locations and behaviors are rejected. Targeting cannot change after create.

#Reddit

Age, income and radius are not available. Targeting can be changed after launch with PUT /v1/ads/{adId}.

#ChatGPT

ChatGPT ads target by country only.

#Endpoints