get_signals. You can
then target one of those signals on a package in create_media_buy. Most of
this page is for anyone who calls a storefront’s AdCP endpoint directly, with
their own agent or SDK. If you buy through Apostra, see
Searching a seller’s signals in Apostra.
What a storefront returns
A storefront returns the signals its inventory sources report to Apostra. It keeps them in a catalog that Apostra refreshes in the background, the same way it keeps the catalog of products. Each signal carries:
The
get_signals answer names none of the storefront’s inventory sources,
their accounts or their own ids for a signal. When the storefront’s signal
catalog holds a signal, a product from get_products names it in its signal
options and included signals with the same signal_ref and
signal_agent_segment_id that get_signals returns. A product can still carry
an inventory source’s own reference: when that source’s signals could not be
refreshed or were for one account only, or for a signal get_signals does not
list. You can target such a reference on a buy as it is.
When some of a seller’s signals could not be read from its inventory sources,
or a new inventory source’s signals have not been read yet, the answer carries
incomplete with scope signals: the list may be missing some, so ask again
later. An inventory source that does not offer signals at all leaves the
answer complete.
Two ways to ask
get_signals has two modes.
discovery_mode: "wholesale"returns every signal you can use, sorted by name, in pages of up to 100 (50 by default). The answer carrieswholesale_feed_versionandpricing_version. Send them back asif_wholesale_feed_versionandif_pricing_versionand the storefront answersunchanged: truewhen nothing changed.discovery_mode: "brief"(the default) looks signals up. Sendsignal_refsto read particular signals,signal_specto search by words, or both. Asignal_specmatch is a word match against each signal’s name, description, provider and categories, ranked by how many of your words it contains. Asignal_speccan be up to 500 characters, and a request can look up at most 100signal_refsandsignal_idstogether; a larger request is refused withINVALID_REQUEST.
filters (catalog_types, data_providers, max_cpm,
max_percent, min_coverage_percentage), countries and destinations.
A signal that names no countries is not limited by country. destinations
matches when it names the storefront’s own endpoint. Each of destinations,
countries, data_providers and catalog_types takes at most 250 values; a
longer list is refused with INVALID_REQUEST.
Page through with pagination.cursor. A cursor belongs to the answer it came
from: if the storefront’s signals change while you page, the next page is
refused with INVALID_REQUEST and you start again without a cursor.
get_signals needs AdCP 3.1 or later. A request pinned to 3.0 is refused with
VERSION_UNSUPPORTED, because AdCP 3.0 requires a price and coverage figure on
every signal, which a source need not report. On 3.1 and later,
get_adcp_capabilities lists signals with
signals.discovery_modes: ["brief", "wholesale"].
What an account changes
account is optional.
- Without an account you get every signal the storefront’s live inventory
sources report, as a public answer (
cache_scope: "public"). A source whose own signal list was for one account only is left out. - With an account you get only the signals from the inventory sources that
account can buy through (
cache_scope: "account"). The feed and pricing versions belong to that account’s view. The account is checked the way product discovery checks it: anaccount_idmust be one you hold, and a brand and operator are accepted only as another name for an account you already synced. See Discovering products on a storefront needs an account.
The signal reference
Most signals carry asignal_ref that names the storefront as the source:
signal_id stays the same for as long as the source keeps reporting the
signal and Apostra keeps the key it is derived with. If Apostra changes that key,
every storefront’s signal_ids change at once. A reference you already hold
keeps working on a buy while Apostra still accepts the earlier key. A buy that
sends a reference Apostra no longer accepts is refused with
invalid_signal_targeting_groups, and you call get_signals again for the
current references. The signal_id reveals
nothing about the source. A signal the source names by its
data provider’s published reference (scope: "data_provider", with
data_provider_domain) keeps that reference, so the same provider signal reads
the same on every seller that carries it. A storefront reference names the
storefront, not the provider, so you cannot check the seller’s right to resell
a provider’s signal through that provider’s adagents.json.
Targeting a signal on a media buy
Send thesignal_ref in a package’s
targeting_overlay.signal_targeting_groups on create_media_buy or
update_media_buy:
INVALID_REQUEST
and the reason invalid_signal_targeting_groups, before any seller approval,
and nothing is sent to the source. Send the signal_source_url exactly as the
storefront returned it: the same reference under another address for the
storefront is refused. Call get_signals again for current references and
send the package again.
When the signal has pricing_options, AdCP has you send the
pricing_option_id of the price you choose in the signal’s entry. On a product
a storefront puts together for your brief, a priced signal is buyable when the
product’s seller bills it; see Priced signals below.
The create_media_buy answer echoes each package’s
signal_targeting_groups as you sent them, with the storefront’s references.
On update_media_buy, a package’s targeting_overlay changes only the
dimensions you send, as AdCP defines: leave signal_targeting_groups out to
keep the package’s signals, or send null to clear them.
Signals on a storefront’s own products
A product a storefront puts together for your brief lists its signals in AdCP fields, with the samesignal_ref that get_signals returns.
included_signalsare signals built into the product. They describe what the product is, its price already covers them, and you do not select them. A product with exact age targeting lists its age first, with its data provider inext.apostra.data_provider. Each other included signal carries its provider indata_provider, asget_signalsdoes.signal_targeting_allowed: truemeans you can add signals to a package of the product throughtargeting_overlay.signal_targeting_groups. A product says so when the inventory it is sold from runs on Apostra’s embedded sales agent and the product is not guaranteed. A fixed-price (guaranteed) package takes no added signals for now: its delivery was forecast without them, and a narrow audience could keep it from delivering. A buy or update that adds signals to a package whose pricing option is fixed-price is refused at once withinvalid_signal_targeting_groups. On a product with both a fixed and an auction price, choose the auction one to add signals.signal_targeting_optionslists up to 20 signals from that inventory that you can add, chosen for the brief the product was put together for: the storefront picks the signals that suit the audience the brief describes, best fit first, whatever words they are named in. When it picks none it can offer, the list is the widest-reaching signals instead: highestcoverage_percentage, then by name.get_signalsis the full menu: a package can target any signal it serves for that inventory, subject to the checks below. Each option carries itssignal_ref, thesignal_agent_segment_idget_signalsserves,name,description,data_providerand value type. When the product’s seller bills a selected signal’s price (see Priced signals), the options include priced signals, each with only thepricing_optionsthe product’s price can take: in its currency, priced per impression. Otherwise they are the publisher’s own data that costs nothing, and carry nopricing_options. A third party’s data with no price is not offered, since its data cost is unknown, and neither is an age signal.- An option you can only use to exclude an audience says
allowed_targeting_modes: ["exclude"]. - Each option’s
selection_groupnames the ad-server targeting it uses (audience_segment,custom_key_valueorgam_custom_key), andsignal_targeting_ruleslists those groups. Ananygroup can’t mix them. An option that combines several targeting criteria has aselection_groupof its own: it can’t be an alternative to any other signal.
included_signals list at most its age, and it has no
signal_targeting_options. It still says signal_targeting_allowed: true,
and get_signals is the menu: its answer carries incomplete with scope
signals whenever the catalog read was partial.
Priced signals
On a product a storefront puts together, a signal with a price is buyable when the seller’s ad server bills a selected signal’s price on the line item it books. Apostra’s embedded sales agent does this on Google Ad Manager. On other inventory, a buy that selects a priced signal in anany group is refused at
once with INVALID_REQUEST and the reason invalid_signal_targeting_groups,
before any seller approval: choose a signal from the product’s
signal_targeting_options and send the package again.
When the seller bills it:
- Name the price you choose with
pricing_option_idin the signal’s entry. An entry for a priced signal with nopricing_option_id, or one that is not among the signal’spricing_options, is refused. - The storefront passes a
pricing_option_idto the seller only for a price it charges you. One you send for a free signal, for a signal in anonegroup, or for a signal the product already includes is not passed on, so the seller can’t bill it. - An entry that names a
pricing_option_idthe storefront can’t check is refused at once, before any seller approval. That happens when the storefront can’t find the signal among the seller’s signals, whatever reference you used: name it by thesignal_refget_signalsreturns. It also happens when the storefront hasn’t read all of that seller’s signals just now (retry shortly), and when the package’s product is one the seller sells as is rather than one the storefront put together, unless that seller is Apostra’s embedded sales agent billing signal prices or has passed priced-signal certification (see Priced signals on products a seller sells as is). - The price is added to the package’s rate. A
cpmprice adds its CPM. Apercent_of_mediaprice adds that share of the package’sbid_price, capped at itsmax_cpm; a package with nobid_priceis refused. Signals in one child group are alternatives, so only the highest price in each group is charged, and the groups’ prices add up. A $2 CPM signal on a package bidding $10 CPM books at $12 CPM, and delivery reports that rate and its spend. - The price must be in the currency of the package’s pricing option, and the package must be priced by CPM. Otherwise the buy is refused.
- A signal in a
nonegroup only excludes an audience and is not charged, unless the signal can only exclude. - A signal the product already includes is covered by the product’s price.
If you send a
pricing_option_idfor it, the storefront does not pass it to the seller, and you are not charged for it again. - The product’s price includes the data price of its own priced signals, and
the seller bills that data on its line item. On an auction package the
storefront sends your
bid_priceto the seller as a media bid, less the data price, so the line item’s rate, media plus data, is your bid: a $2 CPM included signal on a package bidding $12 CPM books a $10 media bid. Apercent_of_mediaprice is taken of that media bid, for an included signal and for one you add. A bid that would leave less than the seller’s own floor for media is not sent, and the buy fails withinvalid_signal_targeting_groups: bid at least the product’sfloor_price. What you pay doesn’t change. An update can’t change thebid_priceorbiddingof such a package, since its media bid was set when it was booked: add a new package with the new bid throughnew_packagesinstead. - A package’s signal price is set when it is booked. An update can’t add,
remove or change a priced signal on a booked package: add a new package
with it through
new_packagesinstead. On a package charged apercent_of_mediaprice, an update also can’t regroup its priced signals or change itsbid_priceorbidding, since the price was taken of the bid it was booked with.
Priced signals on products a seller sells as is
These products come from the seller’s own catalog: the storefront passes them through rather than putting them together for your brief. Apostra’s embedded sales agent. On a product the embedded sales agent sells as is, a priced signal is buyable when the agent bills a selected signal’s price on the line item it books, as it does on Google Ad Manager: the same condition as on a product a storefront puts together. When it does:- Name the price you choose with
pricing_option_idin the signal’s entry. It must be one of the pricesget_signalsserves for the signal, which are the ones the agent bills. A price only the product lists in itssignal_targeting_optionsis refused. - The price is added to the package’s rate, and that is what you pay: the
product’s fixed price, or your
bid_priceon an auction package. A $1 CPM signal on a product priced at $15 CPM books at $16 CPM. Apercent_of_mediaprice adds that share of the same rate, capped at itsmax_cpm; on an auction package with nobid_priceit is refused. - Signals in one child group are alternatives, so only the highest price in each group is charged, and the groups’ prices add up, as the agent bills them. AdCP pricing groups don’t change this.
- A fixed-price package can take priced signals on these products.
- An entry for a priced signal with no
pricing_option_idis refused: name one of its prices. - A package’s signal prices are set when it is booked. Once a package has a
priced signal, an update that names its
signal_targeting_groupsis refused, even unchanged: leave them out to keep them, or add a new package throughnew_packages. A package charged apercent_of_mediaprice also can’t change itsbid_priceorbidding.
pricing_option_id for one of its priced signals is refused at once with
invalid_signal_targeting_groups, before any seller approval, and the reason
says the seller doesn’t bill signal prices.
Other sellers. On another seller’s product, priced signals aren’t
available yet. They open for a seller once its sales agent passes Apostra’s
priced-signal certification, and no seller can pass today: the part of the
check that confirms a seller billed the price once isn’t built yet. Until a
seller passes, a package that names a pricing_option_id for one of its
priced signals is refused at once with invalid_signal_targeting_groups,
before any seller approval, and the reason says the seller hasn’t passed. A
priced signal sent without a price is sent and charged nothing, as before.
See Certification.
A seller will pass when a certification test buy that selected a priced signal
was accepted as sent, delivery was reported, and the seller billed the media
rate plus that signal’s price, once. A pass counts while the evidence it judged
is less than seven days old. The rest of this section describes buying from a
seller that has passed.
When the seller has passed:
- Name the price you choose with
pricing_option_idin the signal’s entry. An entry for a priced signal with nopricing_option_idis refused. - When the product lists the signal in its own
signal_targeting_options, the prices listed there are the ones the seller bills on that product. A signal it lists without prices is bundled into the product’s price or costs nothing extra on it, so it is free. For a signal the product doesn’t list, the pricesget_signalsserves apply. - The storefront sends the signal to the seller as the seller’s own reference,
with the
pricing_option_idyou named. - The price is added to the package’s rate, and that is what you pay. A
cpmprice adds its CPM: a $1.75 CPM signal on a product priced at $8 CPM books at $9.75 CPM. Apercent_of_mediaprice adds that share of the package’s rate, capped at itsmax_cpm, and only on a fixed-price package: on an auction package the seller takes it of a clearing price that isn’t known when the package is booked, so it is refused. A flat fee, or any other price that isn’t charged per impression, can’t be bought this way. Every price must be in the currency of the package’s pricing option, on a package priced by CPM. - Each signal you select is charged once, whatever child group it is in. A
seller can put signals in a pricing group (AdCP
pricing_group) and charge only the highestcpmprice of the ones you select from it (highest), or each one (each). Apercent_of_mediaprice is always charged on its own. The rules come from the seller’s ownget_signalsanswer (signal_pricing_group_rules), and a rule the product states in itssignal_targeting_rulesreplaces the seller’s for that group. A group with no rule is chargedeach, as AdCP sets out. - Apostra stores the seller’s
get_signalsrules each time it reads the seller’s signals in full, and reads them in full until it has stored them. Until then, or when the rules the seller or the product declares aren’t valid AdCP, a package that selects two or more priced signals from one pricing group whose rule isn’t known is refused: select one of them. - A package’s signal prices are set when it is booked, and the seller may
reprice its options later. So once a package has a priced signal, an update
that names its
signal_targeting_groupsis refused, even when the signals are unchanged: leavesignal_targeting_groupsout of the update to keep them. To select different priced signals, add a new package throughnew_packages. An update can’t add a priced signal to a package booked without one either. - If Apostra can’t read whether the seller has passed just now, a package that
names a
pricing_option_idfor one of its signals is refused with a reason to retry shortly.
Groups the seller’s ad server can apply
Signals in anany group are alternatives, and the seller’s ad server can make
alternatives only of audience segments, or of values of one custom-targeting
key. A buy is refused at once with invalid_signal_targeting_groups, before
any seller approval, when an any group:
- mixes audience segments with custom-targeting key signals
(
custom_key_valueorgam_custom_key); - holds values of more than one custom-targeting key;
- holds a signal that combines several targeting criteria together with other signals; or
- holds a signal that can only exclude.
any group. A group with a single signal takes any signal
except one that can only exclude.
A none group excludes each of its signals separately, so it takes any mix.
A signal_ref that names more than one of the seller’s signals is refused the
same way: send the signal’s signal_agent_segment_id with it.
The same rules apply to the signal groups a storefront product stores. A
storefront does not compose a product that offers signals as alternatives the
seller’s ad server can’t book, such as two age bands that sit on different
custom-targeting keys. A product stored that way before the rule existed is
refused at once with invalid_signal_targeting_groups, before the buy is sent
to the seller. The message names the group and its signals; choose another
product, or ask the seller to recompose it. A seller whose sales agent declares
that it books any signal combination on every product of the buy is not held to
these rules.
Searching a seller’s signals in Apostra
A buyer account in Apostra reads one seller’s signals withsearch, the same
read a buyer’s own agent makes through the Apostra MCP server or HTTP API:
filter.sellerAccountIdnames the seller by its Account id, thesellerAccountIdon a seller or product result. One search reads one seller.filter.advertiserIdnames the advertiser whose account with that seller is used. Apostra asks the seller’s storefrontget_signalswith that account, so you see only the signals from the inventory sources the account can buy through (see What an account changes). When your account has only one active advertiser, it is filled in for you.querysearches by words, assignal_specdoes in brief mode. Without aqueryyou get the seller’s whole list, sorted by name.filter.dataProviderkeeps only signals from these data providers. It matches the provider’s name exactly, ignoring case, so copy the name from an earlier result. To search by part of a provider’s name, such as “Polk”, put it inquery.limitsets the page size, up to 100 (50 by default). For the next page, send the returnednextCursorascursor, with the same query and filters.
deployments.
The search is refused, never answered with an empty list, when:
- your advertiser has no account with the seller yet, or the account needs attention: open Media Partners to see where it stands;
- the seller is a platform such as Meta or Snap, which does not offer a signal catalog through Apostra. That does not mean it has no signals.
signal_ref unchanged in
targetingOverlay.signal_targeting_groups on that seller’s product in
save_media_buy, with its value_type (a binary signal takes value: true).
A signal can be targeted only on products of the inventory source that reports
it; any other pairing is refused with invalid_signal_targeting_groups, as
described in Targeting a signal on a media buy.