Overview
You can attach structured targeting intent to a campaign when creating or updating it through the V3 MCP surface (save_campaign on /mcp/v3). Targeting records what the campaign intends to reach — geography, language, device type, daypart, and demographic dimensions — and persists that intent with the campaign object.
Campaign targeting is stored and returned on the campaign workspace. When you
create a media buy with
save_media_buy, its targeting can narrow the V3
campaign overlay but can never widen it.Passing targeting to save_campaign
Campaign targeting is thetargetingOverlay parameter, the AdCP targeting
overlay with canonical codes. It is optional. Omit it to leave targeting
unchanged; send it to set the campaign’s targeting:
geo_countries takes assigned ISO 3166-1 alpha-2 codes, plus XK for
Kosovo. A code ISO does not assign is refused with what to send instead: a
territory such as IC (the Canary Islands) points at its ISO 3166-2 code,
ES-CN, for geo_regions, and a grouping such as EU asks for its member
countries. UK is accepted and saved as GB.
The requirement-shaped targeting parameter (requirementId, strength) has
been removed. A call that sends it is refused with VALIDATION_ERROR.
Looking up codes by name
Targeting is saved as codes, but buyers name places. To turn a list of names into codes before you save, callsearch with kind: "targeting_value":
filter.system is required and names the code system. filter.names takes 1
to 100 names. To look up one name, send it as query instead. Sending both is
refused.
The answer has one row per name, in the order you sent them:
Save the matched codes, ask the buyer about each ambiguous name, and check each
unmatched name with them. Every account can use the lookup: Buyer, Seller,
Organization and Developer. It reads reference data, not anything your account
owns, so the answer is the same in every account.
With neither
filter.names nor query, the search lists every value of the
system, ordered by code, one page at a time with cursor.
The lookup uses the same dictionary that refuses a name on save_campaign and
save_media_buy, so a name it matches is the code a refusal would have named.
Reading targeting back
After save,targetingOverlay appears on the campaign workspace returned by
save_campaign and by get(kind: "campaign"). A campaign with no targeting set
omits the field.
Updating targeting
PasstargetingOverlay in a save_campaign update to replace the campaign’s
targeting. Each call is the full desired overlay, not a patch. Send null to
clear it.
Targeting stated in the brief
The campaign brief reaches every seller in a proposal round. Sellers read it to understand the campaign and to choose what to recommend, for example inventory suited to an age group or an age signal they sell. A hard requirement stated only in the brief, such as “please target women 18-55”, is not applied the same way by every seller:- Storefront-built and Agent-supplied storefronts read it from the brief and never refuse a request only because the brief states targeting. Whether it restricts delivery or is used only to recommend products depends on the AdCP version of the request; see Exact Age Targeting.
- Built-in platform adapters read one closed age range from the brief.
- Other sellers interpret the brief with their own sales agent.
targetingOverlay and keep the brief as
written. The brief still goes to every seller as context.
age.kindsays which bounds the age has:range(bothminandmax),minimum(minonly) ormaximum(maxonly). It is required.age.include_unknownis also required — a boolean stating whether to also target people of unknown age. Whethertrueis accepted, and whether an openminimum/maximumbound is accepted at all when you buy, depends on the seller; see each platform’s compatibility page, for example Spotify Ads compatibility.- A
minimum(“18 and older”) ormaximum(“up to 34”) age is a complete request, and the campaign keeps it as you set it, read back as18+. A proposal round closes it for each seller, because product discovery runs closed ranges only. Aminimumis closed at the oldest age the seller declares, or at 99 when it declares none, and is sent as it is to a seller that accepts an unbounded maximum. Amaximumis closed at 18, the lowest age AdCP allows. A seller that still refuses the closed range is named in its ownperSellerentry with its reason; the rest of the round carries on. A range with neither bound is refused when you save it. targetingOverlayreplaces the campaign’s stored overlay. Send the fields already set, such as the campaign’s countries, together with the new one.- Only move a requirement that has a field. A requirement with no structured field, such as gender, stays in the brief only.
- A preference (“ideally 18-55”) or a description of the audience (“our customers are mostly in their 30s”) stays in the brief. A structured field is applied as a restriction wherever the seller supports it.
- Keep the brief and the structured fields consistent. AdCP 3.2 requires a seller to refuse a request whose brief contradicts its structured targeting.
Campaign targeting and media buys
save_media_buy applies the campaign targeting overlay as a guardrail to each
product’s targetingOverlay. An explicit product targetingOverlay supplies
that buy’s targeting, and campaign targeting still narrows it: overlapping
values are kept, and a product value outside the campaign returns CONFLICT.
A product can omit a campaign field to inherit it, or narrow it where the field
has defined containment rules. It cannot widen the campaign audience.
signal_targeting is excluded from the overlay because it is a priced,
product-scoped selection that will come through the signals path. Typed
signal_targeting_groups remains supported.
On a V3 media-buy product overlay, DMAs are numeric Nielsen codes. A DMA name
is refused with an error that names its code, and an unknown code returns
nearby code candidates.
For country, region, metro, postal, language, browser, device type, and device
platform includes, the buy uses the overlap. Excludes are combined. A buy’s
demographic age range is intersected, unknown ages are included only when both
overlays allow them, and accepted age bases are intersected. The stricter age
restriction wins. Each buy daypart must fit wholly inside a campaign daypart
on the same clock; dayparts are never clipped or converted between timezones.
For proximity, named places, and other structured values without a containment
rule, a product must omit the field or repeat the campaign value exactly.
If the included values for the same field do not overlap, save_media_buy
returns a CONFLICT error. The error names the field and includes the campaign
and product values so you can correct one of them. It does not create a media
buy that targets everywhere. Omit a product geography field to inherit the
campaign’s value for that field.
Language, device, daypart, and demographic campaign intent now participate in
this guardrail. A demographic overlay still cannot dispatch while seller
transport is on AdCP 3.1, so save_media_buy rejects it before seller contact.
Postcodes on live media buys
SavingtargetingOverlay.geo_postal_areas on a campaign also sends the
postcodes to the campaign’s live media buys. Give every postal area its
country (or a country-specific system such as au_postcode): some sellers
look a postcode up by its bare code, which can exist in several countries.
Campaign postcodes replace a live buy’s location targeting. A country, region,
or Nielsen DMA the same save does not set is removed from the live buy, so
changing a campaign from regions to postcodes leaves only the postcodes. Media
buys that have ended (completed, canceled, failed, or rejected) are left as
they are.
Removing postcodes from the campaign removes them from the live buy when the
buy still targets a country, region, or DMA afterwards, either one it already
had or one the same save sets. A save that would leave a live buy with no
location targeting is refused, because the buy would otherwise target every
location. Postcodes set through the V2 constraints field are stored on the
campaign but not sent to live buys.
Seller support varies. See each platform’s page under
Ad platform compatibility; for
example, OpenAI Ads
refuses a postcode together with the country or region that contains it, and
does not support postcode exclusion.
Campaign age range at launch
A campaign’s age range (demographics.age) is copied into every package when
the campaign launches. A media buy on a Meta or Spotify storefront that
approves media buys automatically is sent under AdCP 3.2, and the seller
applies the age range.
Every other seller cannot yet apply a campaign age range at launch. That
includes the other built-in platform adapters, a Meta or Spotify storefront
that reviews media buys manually, Storefront-built storefronts and external
AdCP sellers. Their packages are created without the age range, so the media
buy launches and runs without age targeting. The launch response says so with
a demographics_not_applied warning that names each affected product and
package buyerRef.
A product can carry its own fixed age audience. It counts only when the
product delivers that age to every impression, and when the age is an AdCP
included signal, only when the signal states how the ages are known in a way
the campaign accepts: verified or self-declared ages, plus modeled ages when
the campaign allows modeled age. A survey-based or modeled audience claim is
treated as no fixed audience (see
Which products match a requested range):
- Fixed to exactly the campaign’s range: no warning; the product delivers it.
- Fixed to a range inside the campaign’s, such as 18-34 for an 18-55
campaign: the package is bought with the product’s range, on every seller.
The launch response confirms what was sent with a
demographics_narrowedreceipt naming the product and both ranges. That covers a product selected by id or a campaign range changed after you reviewed proposals. - Fixed to a range that reaches ages outside the campaign’s, such as 18-64 for a 25-54 campaign: that media buy is refused unless its seller can apply the campaign’s range, because it would deliver to people the campaign excludes.
Campaign audiences and catalogs
save_campaign also accepts audienceConfig and catalogId. Use
audienceConfig.targetAudienceIds to include up to 100 audience IDs and
audienceConfig.suppressAudienceIds to exclude up to 100 audience IDs. On an
update, deleteMissing: true replaces both lists; otherwise, supplied IDs are
added to the existing lists. catalogId is the public catalog ID returned by
the catalog read surfaces; pass null on an update to remove it.
Both fields are stored and returned by get(kind: "campaign").
Audiences. A campaign with audiences launches when every seller on it takes
its audiences. A seller takes mapped audiences when its own audience support
covers everything a buy needs: finding the audience on the account, checking it
is ready, and targeting and excluding it. Meta, OpenAI Ads, Google and Reddit do
today. An audience that already exists on the ad account a buy runs on is
already one of the advertiser’s audiences, with its own Apostra audienceId,
mapped to that account; see
Audiences already on your ad accounts.
For an audience you upload, map it to the seller account with save_audience
first. Either way, check it reads synced; see
Map event sources and audiences.
A seller that does not take the campaign’s audiences still blocks the launch,
and the campaign readiness response names that seller.
In the buyer beta, an AdCP sales agent whose declaration says it takes buyer
audiences takes the audiences you had it create: one bound to a partner source
with save_audience sellerAccounts[].source (see
Sync a first-party audience).
Each media buy sends a target audience in audience_include and a suppressed
one in audience_exclude, as the AdCP audience_id the seller created it
under, which is your audienceId. A buy waits while the seller has yet to
answer for the audience. It is refused, with the reason, when the seller
reports the audience is not ready (SELLER_OBJECT_SYNC_PENDING; send the buy
again once it reads synced), when the seller’s declaration for the product
does not take the audience’s partner rail (SELLER_OBJECT_INGESTION_UNMAPPABLE)
or does not take both include and exclude (SELLER_OBJECT_TYPE_UNSUPPORTED),
or when its declaration cannot be read (SELLER_OBJECT_CAPABILITIES_UNAVAILABLE).
On such a seller, an id you put in a package’s targetingOverlay.audience_include
or audience_exclude must be the audienceId of one of your audiences on the
buy’s advertiser, and is decided the same way. Any other id is refused with
SELLER_AUDIENCE_MISSING. An AdCP sales agent that declares no buyer audiences
is unchanged: package ids reach it as you wrote them, and a campaign with
audiences does not launch on it.
TikTok does not take campaign audiences yet. A TikTok media buy package can
still include or exclude an audience in its targetingOverlay.audience_include
and audience_exclude, named by its TikTok audience id. The audience must be on
the selected advertiser and ready, with at least 1,000 matched users; one that
isn’t is refused with the reason. See
TikTok Ads compatibility.
Catalogs. A campaign with a catalog launches when every live line sells
through a product that declares it takes that catalog’s type. Otherwise the
readiness response returns catalog_sync_unavailable. Remove the catalog to
launch without it.
Spotify Website traffic - Video views is in internal testing and is not yet generally available. Only our own buyer accounts with testing access can see or book it.
Spotify Website traffic - Page views is also in internal testing and is not
generally available. Select a Pixel exposed by sync_event_sources in
optimization_goals[].event_sources[].event_source_id, with event_type set
to page_view. The Pixel must belong to a delegated, unarchived dataset and
have received a Page View. Spotify may refuse the ad set for eligibility
reasons it does not publish.
Spotify artist and podcast promotion
Spotify Engagement on Spotify products promote an artist or a podcast show. The clicks and video-views products are in internal testing and are not yet generally available. Only our own buyer accounts with testing access can see or book them. To use one, save anoffering catalog with one
item for the artist or show, then attach its catalogId to the campaign with
save_campaign. Every live line on that campaign must take an offering catalog.
Name the target with its spotify:artist:<id> or spotify:show:<id> URI in
offering_id, or its https://open.spotify.com/artist/<id> or
https://open.spotify.com/show/<id> link in landing_url. The offering also
needs a name. A bare Spotify ID alone does not say whether it is an artist or
a show; use a URI or link so the target’s type is clear. Existing podcast-only
stream products continue to accept bare show IDs.
Before creating a campaign on Spotify, Apostra checks that the offering names
exactly one target and looks it up with the connected Spotify Ads account. A
missing, ambiguous or unrecognised target is refused with the reason. If the
Spotify lookup is unavailable, try again when it is available. A link names
the promoted item; it does not prove that the advertiser owns it.
Targeting each product offers
Each product says which targeting you may set on a package for it: its AdCPoverlay_support, such as countries, regions, Nielsen DMA metros or a
frequency cap, with any per-package limits the seller sets. You can book only
what a product offers. A product lists signal_targeting_groups there only when
it also says signal_targeting_allowed: true, as AdCP requires. A product from
a seller’s Apostra-managed sales agent offers you the signals that seller lists
in get_signals, even when the product lists none of its own. A product that
offers you no signals to add leaves the groups out, for example one whose
seller lists no signals in get_signals and whose only signals are the property
signals Apostra manages.
Where you see it:
get_productsreturnsoverlay_supporton each product that declares targeting, in both wholesale and brief results. A product composed from inventory carries the declaration of the inventory product it is built from. See The targeting a product lets you set.- V3
search(kind: "wholesale_product")returnsoverlaySupportandsupportedTargetingon each product that declares targeting. A declaration too large to return inline is left out of search, leavingsupportedTargeting. - V3
get(kind: "wholesale_product")returns one product, by theproductIdandadvertiserIdfrom your search, with its completeoverlaySupport. - V3
get(kind: "seller")returns the seller’s own targeting (targetingandsupportedTargeting). It applies to the seller’s products that declare none of their own.
- Through Apostra’s buyer tools (
save_media_buy,save_campaign,create_media_buys) the refusal is a validation error ontargeting_overlay, for example: “The selected products do not offer the requested targeting: package line-1 targets what product … does not offer: geo_metros system uk_itl1 is not offered by this product (offered: nielsen_dma).” - Through a storefront’s AdCP endpoint the refusal is
UNSUPPORTED_FEATUREwithdetails.reasonundeclared_product_targetingand the same message.
demographics.gender, added in AdCP 3.3) is checked the same
way. A product offers it only by declaring overlay_support.demographics.gender;
demographics: true or an age-only declaration does not cover it. No product
declares gender yet, so a package that targets gender is refused, with
demographics.gender is not offered by this product, rather than sent to a
seller that would ignore it.
A product on a seller’s managed sales agent that the seller hasn’t narrowed
offers the targeting the seller’s ad server can apply, and is checked against
that in the same way. A product on any other source that declares no targeting
of its own isn’t checked this way. The seller’s own targeting applies to it
instead, and a booking that asks for targeting the seller can’t apply is
refused.
Buying some of a product’s shows
A product that sells collections, such as the shows of a podcast network, lists them in AdCPcollections, and its upcoming episodes in installments.
Its collection_targeting_allowed says whether you may buy only some of them.
To buy one show or a few, set the package’s
targeting_overlay.collection_selection to mode: "selected" with the shows
you want, each named by its publisher_domain and collection_ids. The
selection is checked when you save, create or update the buy, as above:
- A show the product doesn’t list is refused, naming it, for example “collection_selection names collections this product does not include: northwind-audio.example/night-shift”.
- A product that doesn’t set
collection_targeting_allowed: trueis sold as one bundle. Selecting some of its shows is refused. Naming all of them, ormode: "default", books the whole bundle. - A product that lists no shows, or doesn’t disclose them, isn’t checked this way. The seller decides what it can book.
collections, installments
and collection_targeting_allowed its source declares, under these AdCP
names.
Rollout and release check
This is available immediately on the public V3save_campaign and
get(kind: "campaign") surfaces; it has no separate customer enrollment or
feature flag. The Buyer V3 API release owner verifies the release through the
automated PR Acceptance Tests catalog contract proof, then confirms in the
released environment that a campaign can save and read back an audience or
catalog and that a launch attempt returns the seller-sync blocker.
The release check passes only when all three behaviors agree: save persists the
requested IDs, get returns them, and launch stays refused while seller sync
is unavailable. Treat a missing readback value, a launch that succeeds, or a
blocker other than the seller-sync refusal as a mitigation trigger. Roll back
the release or remove the audience/catalog from the affected campaign; do not
override the blocker or treat the objects as delivered.
Backward compatibility
V3save_campaign no longer accepts the requirement-shaped targeting
parameter, and V3 campaign reads no longer return it; use targetingOverlay.
Existing campaigns keep their stored targeting, and their targetingOverlay
reflects it. The v2 campaign workspace response still returns targeting for a
campaign that stored it.