Skip to main content
A media partner is turned on for an advertiser automatically only when both of these are true:
  • 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.
Every other media partner is available to turn on, but stays off until you turn it on, however well it overlaps. See When channels and markets match but it is still off. When overlap is what is missing, Apostra says which of the two dimensions is missing. You see it in the Connections page, and your agent reads it from the 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:
Each entry in 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:
Gaps appear only when channels and markets are what decide availability. If something else decides it, such as the media partner not being a market maker, the advertiser turning the media partner off, an account-level Always exclude, or the media partner not being listed or not able to take buys yet, 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_advertiser with the advertiser’s id and the new channels or brandCountries. Send an empty list to choose All channels or All countries.
Only change the footprint to what the advertiser actually buys and where it actually operates. If the media partner genuinely does not sell in the advertiser’s channels or markets, it is correct that it isn’t available.

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 the seller read for that advertiser you see:
  • partnerStatus: "AVAILABLE"
  • qualified: false and an empty qualificationGaps on the advertiser’s entry in controlPlane.activation.advertisers, because nothing about the advertiser’s channels or markets is stopping it
  • preference.reason: "no_automatic_match" on the same entry, when your account has per-advertiser control and the read includes preference
Read 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_connection with the seller and selection: { 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_connection with advertiserActivation: { 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, and qualificationGaps 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 reads partnerStatus: 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_connection with advertiserActivation: { "advertiserId": "<advertiserId>", "decision": "ENABLED" }.
  • For every advertiser. Set the media partner to Always include for your account, described above.
Apostra then sets up the advertiser’s account with the media partner, which takes a few minutes (see below). The media partner sees only how many buyer accounts and advertisers have switched it on, never which ones.

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 same seller 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 the seller read answers them separately.
  • Is it in your list? Read controlPlane.selection.selected. It is true when the media partner matches your advertisers (or you set it to Always include), and false when 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

The seller 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.
Apostra does not yet store the channel handles and proof of channel ownership 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 AdCP collection 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. 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.
The Media Partners page maps its actions to these decisions: 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:
  • action is applied (the decision was stored), unchanged (it was already in place, or REMOVE had nothing to remove) or failed (nothing was stored; read errors). The call is an error only when every media partner fails.
  • decision is the decision now stored for that media partner. For REMOVE it is the one the server chose. It is null when the media partner failed.
  • accountRequestsQueued is 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’s controlPlane.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 with replayed: true instead of applying the change twice. A key reused for a different change is refused with CONFLICT. Resend a failed media partner with a new key.
The list form has no mutation receipt. The single-media-partner form is unchanged.

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:
  1. 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.
  2. Record a supply request for the publisher’s domain and the channel you want to buy, for example hurriyet.com.tr and display, from the Media Partners page or by asking the Apostra assistant. With save_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.
A seller on Apostra may already sell some of a publisher’s inventory, for example a network or an exchange that resells it. That does not make it the right seller for that publisher: it may not be the publisher’s own route, carry the inventory you want, or sell it in your market. You decide whether to buy through it, and you can still invite the publisher and record a supply request for the publisher itself.
  • Connect in five minutes: connect a media partner and read its seller and connection objects.
  • Manage ads: set up advertisers and run campaigns across media partners.