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. 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 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 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. 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. 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, no filter.partnerStatus, no filter.selected, no filter.memberOf and no filter.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.
  • query searches 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 carries controlPlane.selection.selected and the decision, so you can tell where it stands for you. Without filter.sort, the closest text match comes first.
  • filter.selected keeps the media partners in your list (true) or the rest (false, which includes the ones you excluded). filter.memberOf keeps a network’s members: send the network’s sellerAccountId.
  • filter.partnerKind keeps the media partners whose partnerKind is any of the values you send: platform, media, or null for a media partner with no kind (see What a media partner sells). It uses the rule the partnerKind count uses, so the total of 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. creator is refused until a media partner can read it.
  • filter.property with filter.country keeps the media partners that can sell one property in one country, ranked best first. See Who can sell me this property, here.
  • filter.sort is name (the default, A to Z, ties broken by media partner) or followers. followers is refused with UNSUPPORTED_FEATURE until Apostra holds creator data. Any other value is refused, not ignored. With filter.property and no filter.sort, the best property claim comes first.
  • One channel rule. Every filter.channel matches 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 nextCursor when more follow. It is opaque: send it back unchanged, with the same query, filters and filter.sort. A page that has media partners before it also returns previousCursor, which works the same way and returns the page before, up to limit media partners, so a page can offer Previous and Next. The first page has no previousCursor. A value that is not a cursor a media partner search returned, or a number cursor from before this change, is refused with INVALID_CURSOR. Every page reports the total of the whole search. There is no page number to jump to, and no cursor for the last page.
  • One advertiser’s status. filter.partnerStatus with filter.advertiserId reads 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 than limit, or none, and still carry a nextCursor. Keep sending the nextCursor back until a page returns none. previousCursor reads backwards the same way, within the same limit, so the page before can also be short. Such a search returns totalLowerBound (“at least this many”) in place of total unless one call read the whole list; a page reached with previousCursor always returns totalLowerBound. It used to refuse a search that narrowed to more than 5,000 media partners; that limit is gone.

Count media partners

Add groupBy 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 for channel 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.
The values listed are the channels, and the countries, that at least one matching media partner names. An official platform integration names the channels Apostra lists for it, such as 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:
  • groupBy of runsOn, language, topic or offers returns UNSUPPORTED_FEATURE naming the field, because Apostra holds no creator data to count them by yet.
  • groupBy of sellerType, transactable or partnerStatus returns VALIDATION_ERROR listing the fields that can be grouped by.
  • groupBy with both filter.partnerStatus and filter.advertiserId returns UNSUPPORTED_FEATURE: that status is read media partner by media partner and in part, so a count of it would be short. Drop filter.advertiserId to count by the account’s status, or list the media partners.
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.
Apostra checks 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.
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.