- 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.
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 does not yet ask media partners for collections or store them. Until it
does, the include returns an empty collections list with
collectionsNotCollected: true, never an error. An empty list then says nothing
about the media partner.
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.
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.