- The two overlap on channels and on markets. The advertiser’s channels and countries come from its setup. The media partner’s come from what it declares on its Listing, or from its platform when it is an official platform connection.
- The media partner is a market maker for that market: a global market maker, or a regional market maker for a market the advertiser is in. Apostra turns market makers on for every advertiser they overlap with.
seller read.
Overlap alone does not switch every media partner on. Apostra switches a media
partner on for your advertisers automatically when it is a market maker. A
platform you connect with your own login is on once you connect it. Any other
media partner, including a publisher that has just joined Apostra, appears for
an advertiser only after you switch it on yourself: see
Switch on a media partner that is not automatic.
Your own organization’s Storefronts are on already
A Campaign management account sees and buys from the Storefronts and Listings of the other accounts in its own organization, its own supply, with no switching on and no overlap to measure. A company that both sells and buys plans and buys its own supply from its Campaign management account like any other seller.- Every advertiser, at once. Each advertiser of the Campaign management account has the organization’s Storefronts on. Channels and markets do not have to overlap, and the Storefront does not have to be a market maker.
- Before Scope3 lists it. A new Storefront starts as
PENDING_REVIEW, and the organization’s own buyers can use it straight away. Marketplace participation turned off, or a listing Scope3 hid, hide it from buyers outside the organization only. The Storefront is still available to its own organization. - When it can take buys. Apostra opens the advertiser’s account with the Storefront once the Storefront can take new business: it is not on the intake hold (Hold or resume new business) and its readiness blockers are cleared. Until then it stays on the Connections page without an account for the advertiser.
- No approval step between the two accounts. The Storefront’s account
approval policy does not apply to an account of its own organization: Apostra
accepts the account and records the reason as
account_intake_same_organization_accept. This holds whether the Storefront reviews or rejects new accounts, and whatever payment terms the account asks for. A decision the seller already made about a particular account stands, and a Storefront whose own external sales agent decides its accounts still lets that agent decide. - Your choices still apply. Turning a Storefront off for the whole account (Always exclude) or for one advertiser keeps it off. The seller’s other rules apply as they would to any buyer: its business rules, discounts, buyer instructions, pricing and the terms it requires.
- Not your own account’s Storefront, and not the test storefront. The Marketplace never shows an account its own Storefront. The hidden test storefront Apostra creates so an organization can certify its own agents is not supply for the organization’s buyers.
What has to overlap
An advertiser that chose All channels or All countries overlaps with
every media partner on that dimension. An advertiser that has not chosen a
dimension at all has no overlap to measure, so it is not matched automatically
until it answers.
Read why it isn’t available
Read the media partner for one advertiser:controlPlane.activation.advertisers carries qualificationGaps.
It has one entry for each dimension that stops this advertiser matching this
media partner, and it is empty when channels and markets match.
The values are codes, not display names. For example, an advertiser that buys
ctv in FR and DE, against a media partner that sells display in ZA,
reports both dimensions:
qualificationGaps is empty, because changing the
advertiser’s channels or markets would not help. Those reasons have their own
fields: qualified, preference, and selection.unavailableReason. So an
empty qualificationGaps does not mean the advertiser is available.
Fix it
Change the advertiser’s channels or countries so they overlap with the media partner:- In the Connections page. Each gap has an Edit advertiser channels or Edit advertiser markets button. It opens the advertiser’s setup.
- Through your agent. Call
save_advertiserwith the advertiser’sidand the newchannelsorbrandCountries. Send an empty list to choose All channels or All countries.
When channels and markets match but it is still off
A media partner that is not a market maker is never turned on automatically, even when the advertiser’s channels and markets overlap with it completely. On theseller read for that advertiser you see:
partnerStatus: "AVAILABLE"qualified: falseand an emptyqualificationGapson the advertiser’s entry incontrolPlane.activation.advertisers, because nothing about the advertiser’s channels or markets is stopping itpreference.reason: "no_automatic_match"on the same entry, when your account has per-advertiser control and the read includespreference
sellerType on the same seller object to tell the cases apart: a
global_market_maker or regional_market_maker that overlaps is turned on for
you, an apostra_seller is not.
Changing the advertiser’s channels or markets will not help. To use the media
partner, turn it on:
- For your whole account: set it to Always include on the Media Partners
page, or call
save_connectionwith the seller andselection: { decision: "ALWAYS_INCLUDE" }. See When matching doesn’t apply. - For one advertiser, where your account offers per-advertiser control: turn
it on for that advertiser on the Media Partners page, or call
save_connectionwithadvertiserActivation: { advertiserId, decision: "ENABLED" }.
When matching doesn’t apply
An account-level Always include for a media partner overrides matching, so an advertiser is available to it whatever its channels and markets, andqualificationGaps is empty. Always exclude turns the media partner off for
every advertiser, whatever the overlap, and qualificationGaps is empty there
too.
Switch on a media partner that is not automatic
Any other media partner readspartnerStatus: AVAILABLE for your advertisers
until you switch it on, even when an advertiser has no
qualificationGaps. Its products do not appear in discovery for an advertiser
until then. Switch it on in one of these ways:
- For one advertiser. In the Connections page, with that advertiser
selected, set the media partner to On. Your agent calls
save_connectionwithadvertiserActivation: { "advertiserId": "<advertiserId>", "decision": "ENABLED" }. - For every advertiser. Set the media partner to Always include for your account, described above.
Where the advertiser’s account with a media partner stands
Being available is not the same as being ready to search. A media partner opens an account for the advertiser before Apostra can search it for that advertiser, and that can take a while. The sameseller read says where each account
stands, so you do not have to work it out from the activation state.
Each entry in controlPlane.activation.advertisers carries accountReadiness:
An account needs your buyer account’s operator domain to be a registrable
domain, such as
agency.com, not a subdomain such as team.agency.com, because
media partners check the operator against the brand’s trust.json grants,
which name registrable domains. When the operator is a subdomain, no media
partner can open the account, so the advertiser shows
state: "action_required", requiredAction: "fix_operator_domain" and
accountReadiness: "needs_attention", and request_proposals reports the media
partner as needing your attention. Set a registrable operator domain with
save_buyer_operator (see
Set up operator and brand identity).
controlPlane.activation.accountReadiness adds two counts over the listed
advertisers: pending and needsAttention. On a read for one advertiser the
list holds that advertiser only, so each count is 0 or 1.
A buyer agent sees only the advertisers it is granted, and a
credential scoped to one advertiser sees only that advertiser. Its list, these
counts, and controlPlane.activation.state and requiredAction cover those
advertisers alone, and an agent with no grant sees an empty list.
controlPlane.selection and controlPlane.billingPolicy belong to the buyer
account and read the same for every caller.
The Media Partners page shows how many media partners still have an account being
set up as N pending, and files each advertiser under the status the read
reports. An API from before this field omits it, and a missing value says
nothing about the account.
The same entry names the account in sellerAccountMappingId: the media
partner’s own id for the advertiser’s account, or null when there is none
yet. It is not the media partner’s Account id, which is sellerAccountId at
the top of the seller object; never send it as a sellerAccountId.
Where a media partner stands: ready, needs you, or waiting
Being in your list and being ready to buy are two questions, and theseller
read answers them separately.
- Is it in your list? Read
controlPlane.selection.selected. It istruewhen the media partner matches your advertisers (or you set it to Always include), andfalsewhen it is only in Explore or you set it to Always exclude. - Can you buy from it, and what is the one thing to do next? Read
partnerReadiness.
partnerReadiness is null when the media partner is not in your list.
Otherwise it is { state, nextStep }:
nextStep is { action, resolvedBy }. The API picks one step when several
things are wrong, in this order: a media partner nobody can buy from, then
signing in, then billing, then advertiser setup. Render it as given; do not work it out again from the activation fields.
A permission your sign-in lacks counts only when buying needs it. When a
connection works but its sign-in is missing such a permission, the state is
needs_you with reconnect and resolvedBy: "buyer", a sign-in step. Today
that is Snap: Snap requires a Public Profile on every creative, so a Snap
connection made without the Public Profile permission cannot assign any
creative until you reconnect it (see
When a connection needs a reconnect for new access).
A missing permission that only limits something optional stays a note on the
connection (connectionState.credentialAccess) and does not change the state.
A media partner nobody can buy from is never ready. When the seller read says
transactable: false, that comes before every other step: the state is
waiting, nextStep.action is null (there is nothing anyone on your side can
do), and resolvedBy comes from unavailableReason. It is provider for
seller_opted_out and not_published, and apostra for pending_review and
cannot_transact. This is the one case where action is null.
resolvedBy uses the same words as connectionState.accountDiscovery.resolvedBy:
buyer, apostra or provider. A problem only Apostra can fix is never shown as
the media partner’s, and a problem on the media partner’s side is never shown as
yours: needs_you is exactly resolvedBy: "buyer".
Each advertiser in controlPlane.activation.advertisers carries its own
partnerReadiness. It is null when the media partner is not in your list, or
when the advertiser owes it no setup (see accountReadiness above). The
media partner’s own partnerReadiness reads across those advertisers and puts
a step you can take before any step another party owes. So one advertiser
waiting on the media partner’s billing never hides another advertiser’s setup
step that you can do: the media partner reads needs_you, while each advertiser
keeps its own step. Within each group the order above decides (signing in, then
billing, then advertiser setup), and one advertiser’s unfinished setup shows on
the media partner while the others stay ready. A media partner nobody can buy
from is the exception: it comes first, because nothing you can do fixes it. On a
read for one advertiser, both describe that advertiser only.
partnerStatus (ACTIVE, NEEDS_CONNECTION, AVAILABLE) is deprecated. It
keeps its values and meaning exactly, and is not worked out from
controlPlane.selection.selected or partnerReadiness, so the two do not map
one to one: a media partner that needs your own login and has no connection
reads NEEDS_CONNECTION whether or not it is in your list. It is removed no
earlier than three months after partnerReadiness reaches every buyer account,
with the date announced in the release notes.
What a media partner sells: platform, creator or media
Theseller read says what a media partner sells in partnerKind. Apostra
works it out and never takes the partner’s own word for it, so filter and group
on it without checking the claim yourself.
Owning a property does not change the kind, and neither does being its sales
house, a rep firm or a reseller.
partnerKind is null when no rule applies, and a null is not a guess, so do
not read it as media. Two rules apply today:
- A media partner that is an Apostra integration with an ad platform is
platform. - Any other media partner with at least one property claim, of any status (see
Property claims), is
media.
creator needs, so no media partner reads creator yet, and a media partner
that is neither a platform nor has a property claim reads null.
If a media partner’s kind is wrong, tell Apostra through your usual contact. Staff
review the dispute in their supply review.
Creator cards
A creator’s card is its AdCPcollection data: images, sample posts, talent and
the channels it distributes on, as the creator sent them. Ask for it with
get(kind: "seller", id, include: ["collections"]). It is an include, so a
search page stays small. The read lists at most 25 collections, the most
recently updated first, with collectionsOmitted counting the rest, and at most
10 sample_content items in each, in the order the creator sent them.
Apostra collects cards from media partners whose agents declare the collection
catalog capability. When a partner has been asked and has no cards, the list is
empty and collectionsNotCollected is false. When its cards have not been
collected, the list is empty and collectionsNotCollected is true, so the
empty list says nothing about that partner.
A proposal carries the cards its products sell. When a media partner’s products
name collections, get(kind: "proposal", id, include: ["products"]) returns
collections beside products, in AdCP’s own collection_cards shape: AdCP
collection objects, each once, matched to a product by the product’s own AdCP
collections selectors (publisher_domain and collection_ids). The list holds
the cards the products name, at most 25, each with at most 10 sample_content
items, and collectionsOmitted counts the rest. The cards arrive on the first
page of the read only, and are read when you read the proposal, so they follow
the partner’s current catalog. A proposal whose products name no card Apostra has
collected has neither collections nor collectionsOmitted. The proposal view
shows one card for each: the creator’s name and face, the channels with follower
counts, sample videos, and a link to their own page.
Recommended by Apostra
recommendation on the seller read is null, or { reasons } with each reason
a code from a closed list. It marks a media partner Apostra recommends, and it
works like this:
- It is never bought and never follows a deal. Apostra works it out without reading any commercial field. Critical supply, market maker status and commercial entitlements neither earn it nor remove it.
- It is only ever positive. A media partner without it reads
null, never a low score. - It is not awarded yet. Apostra has not set the criteria, so the list of
reason codes is empty and every media partner reads
null. When Apostra sets them, each reason code is announced in the release notes first.
search returns it too, so a list can show the mark.
Find media partners with search
search(kind: "seller") lists the media partners you can see. Apostra filters,
orders and pages them in its database, so a search answers the same way at any
number of media partners, and no search is refused for matching too many. The
filters are the ones in the
V3 tool reference.
- What a search covers. With no
query, nofilter.partnerStatus, nofilter.selected, nofilter.memberOfand nofilter.property, a search lists the default list: the media partners you can buy from, and market makers. Any of those five makes it cover every media partner listed on Apostra that you can see, whether or not it is in your list and whether or not you can buy from it yet. querysearches everything. It finds a media partner by part of its name, brand, domain or platform, in your list or not, including one you set to Always exclude. Each result carriescontrolPlane.selection.selectedand the decision, so you can tell where it stands for you. Withoutfilter.sort, the closest text match comes first.filter.selectedkeeps the media partners in your list (true) or the rest (false, which includes the ones you excluded).filter.memberOfkeeps a network’s members: send the network’ssellerAccountId.filter.partnerKindkeeps the media partners whosepartnerKindis any of the values you send:platform,media, ornullfor a media partner with no kind (see What a media partner sells). It uses the rule thepartnerKindcount uses, so thetotalof a filtered search equals that value’s count under the same other filters. It narrows the list the other filters read and does not widen it.creatoris refused until a media partner can read it.filter.propertywithfilter.countrykeeps the media partners that can sell one property in one country, ranked best first. See Who can sell me this property, here.filter.sortisname(the default, A to Z, ties broken by media partner) orfollowers.followersis refused withUNSUPPORTED_FEATUREuntil Apostra holds creator data. Any other value is refused, not ignored. Withfilter.propertyand nofilter.sort, the best property claim comes first.- One channel rule. Every
filter.channelmatches the same way: a media partner matches when its discovery card or its platform integration lists the channel, and a media partner that names no channel matches every channel. Several channels keep a media partner that matches any one of them. - Paging. A page returns
nextCursorwhen more follow. It is opaque: send it back unchanged, with the samequery, filters andfilter.sort. A page that has media partners before it also returnspreviousCursor, which works the same way and returns the page before, up tolimitmedia partners, so a page can offer Previous and Next. The first page has nopreviousCursor. A value that is not a cursor a media partner search returned, or a number cursor from before this change, is refused withINVALID_CURSOR. Every page reports thetotalof the whole search. There is no page number to jump to, and no cursor for the last page. - One advertiser’s status.
filter.partnerStatuswithfilter.advertiserIdreads that advertiser’s status for each media partner from its countries, channels and preferences, after every other filter has narrowed the list in the database. A call reads part of the list: it stops when its page is full, or after about 50 pages or five seconds. So a page can hold fewer media partners thanlimit, or none, and still carry anextCursor. Keep sending thenextCursorback until a page returns none.previousCursorreads backwards the same way, within the same limit, so the page before can also be short. Such a search returnstotalLowerBound(“at least this many”) in place oftotalunless one call read the whole list; a page reached withpreviousCursoralways returnstotalLowerBound. It used to refuse a search that narrowed to more than 5,000 media partners; that limit is gone.
Count media partners
AddgroupBy to count the media partners a search would list, by one field,
instead of listing them. A count reads exactly the filters its list reads, so
the counts add up to the total the same search reports. The call and its
response are described in
Count objects with search.
A count of the default list counts the media partners that list holds. To count
every media partner listed on Apostra, send
filter.partnerStatus with all three
statuses, as above, or any other filter that widens the search.
Channel and region counts overlap
A media partner sells in several channels and countries, so it is counted under every one it has. The counts forchannel and region therefore add up to
more than total, and you must not add them up. The response says so with
overlapping: true, and the text says it too. It never has an otherCount:
the media partners in a value the limit left out are counted in other values
as well.
Each count is exactly what search(kind: "seller") returns when you filter by
that value, with the same other filters. groupBy: "channel" with display
at 40 means filter.channel: ["display"] returns 40 media partners, by the
one channel rule:
a media partner whose discovery card or platform integration lists the channel
matches, and a media partner that names no channel matches every channel, so
it is counted under every one. Regions work the same way, with the region
filter’s rule: a media partner that names no country, or that sells worldwide,
is counted under every country.
social for Meta. A value no matching
media partner names is not listed, and a value that would count zero is left
out. Regions are counted by country, so a country group such as EU is not a
value, though filter.region accepts it. If you also send filter.channel or
filter.region, the count covers the media partners that filter keeps.
These counts are refused rather than answered with an empty or short result:
groupByofrunsOn,language,topicoroffersreturnsUNSUPPORTED_FEATUREnaming the field, because Apostra holds no creator data to count them by yet.groupByofsellerType,transactableorpartnerStatusreturnsVALIDATION_ERRORlisting the fields that can be grouped by.groupBywith bothfilter.partnerStatusandfilter.advertiserIdreturnsUNSUPPORTED_FEATURE: that status is read media partner by media partner and in part, so a count of it would be short. Dropfilter.advertiserIdto count by the account’s status, or list the media partners.
Open the Media Partners page on a search
open_media_partners_page takes the same filter and text as the search above,
so an agent can open the page on what you asked for instead of listing media
partners in chat. All three inputs are optional. A call that sends none of them
opens the page as before.
filter and query with the checks search(kind: "seller")
uses, and refuses a bad value with the same error. For example, filter.sort of
followers is refused with UNSUPPORTED_FEATURE until Apostra holds creator
data, and a region of "" is refused. Any other filter key, including the
rest of the filter search takes, is refused by name, and the error lists the
five keys the page takes. Nothing is read from the words of a message: the agent turns your
request into these inputs.
The result carries the three it opened on as filter, query and tab. The
Media Partners page shows query in its search box today. It applies filter
and tab once your account has the redesigned Media Partners page; until then a
call that sends them still succeeds and opens the page as before.
Change several media partners at once
save_connection changes up to 100 media partners in one call. Send
sellerAccountIds (their Account ids, each once) inside selection or
advertiserActivation in place of sellerAccountId. Everything else about the
change is the same as for one media partner.
REMOVE is a request, never a stored decision, and only the list form takes it.
The server works out what it means for each media partner. One you added (it is
set to ALWAYS_INCLUDE) goes back to DEFAULT, so Apostra may keep it if it
matches your advertisers. One Apostra added (it is DEFAULT and
selection.selected is true) goes to ALWAYS_EXCLUDE. A media partner that is
not in your list has nothing to remove and is answered unchanged.
Each media partner is answered on its own, in the order you sent them. One
refusal does not stop the rest:
actionisapplied(the decision was stored),unchanged(it was already in place, orREMOVEhad nothing to remove) orfailed(nothing was stored; readerrors). The call is an error only when every media partner fails.decisionis the decision now stored for that media partner. ForREMOVEit is the one the server chose. It isnullwhen the media partner failed.accountRequestsQueuedis how many account requests Apostra will send for that media partner, and in total. Adding a network with all its creators can mean hundreds, so read it before you add many. No request goes out during the call: Apostra sends them afterwards, and that count is the advertisers that will each need an account there. It is the same rule Apostra uses to send them, but Apostra can still hold a request back, for example while a billing or account setup step is open. Follow progress on each media partner’scontrolPlane.activation.accountReadiness. Excluding a media partner, or switching an advertiser off, counts 0.- For
advertiserActivation, the count is that advertiser’s request only. idempotencyKey(16 to 255 characters) is optional on the list form. Send the same key and the same change again and you get the first answer back withreplayed: trueinstead of applying the change twice. A key reused for a different change is refused withCONFLICT. Resend a failed media partner with a new key.
Invite a seller that is not on Apostra
When the publisher or seller you want is not on Apostra at all, there is no media partner to match. Do two things:- Send the publisher the signup link, with a short sentence about why:
https://app.apostra.com/signup?intent=storefront. It opens the signup on the media-company path. Sending it contacts nobody on your behalf; the publisher signs up for itself. What the publisher does next is in From signup to your first booking. - Record a supply request for the publisher’s domain and the channel you
want to buy, for example
hurriyet.com.tranddisplay, from the Media Partners page or by asking the Apostra assistant. Withsave_ask(type: "supply") or the Apostra assistant you can also name the countries you want to buy in, for example["NL"]; see Name the countries on a supply ask. A supply request is your own record of demand. It does not invite, nudge or notify the seller, and recording it is not a promise that the seller will join. A supply request for a publisher that is not yet on Apostra also goes to the Apostra lead for the market of the countries you name (or for your account’s market when you name none), who decides whether to contact the publisher. When no lead is set for those markets, the request goes to Apostra’s global lead if one is set, and otherwise is not routed to anyone. Apostra does not promise that the publisher will be contacted, or by when.
Related
- Connect in five minutes: connect a media partner and read its
sellerandconnectionobjects. - Manage ads: set up advertisers and run campaigns across media partners.