> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Why a media partner isn't available to an advertiser

> How an advertiser's channels and markets, and whether a media partner is a market maker, decide which media partners are turned on for it, what qualificationGaps reports when one isn't, and how to fix it.

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](https://docs.apostra.com/v3/media-partner-availability.md#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](https://docs.apostra.com/v3/media-partner-availability.md#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](https://docs.apostra.com/v3/seller-intake-hold.md)) and its
  [readiness](https://docs.apostra.com/v3/seller-readiness.md) 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

| Dimension | The advertiser says | The media partner says | Available when |
| - | - | - | - |
| Channels | The AdCP channels it expects to buy, or **All channels** | The channels it sells in. None declared means every channel | At least one channel is on both sides |
| Markets | The countries it operates in, or **All countries** | The countries or regions it sells in. None declared means every market | At least one country is covered by the media partner's countries, or by a region that contains it, such as `EU` |

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:

```text theme={null}
get(kind: "seller", id: "<storefrontId>", advertiserId: "<advertiserId>")
```

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.

| Field | Meaning |
| - | - |
| `dimension` | `channels` or `markets` |
| `state` | `not_set`: the advertiser has not chosen this dimension. `no_overlap`: both sides chose it and share nothing |
| `advertiserValues` | The advertiser's AdCP channel ids or ISO country codes. Empty when `state` is `not_set` |
| `sellerValues` | The media partner's AdCP channel ids or ISO country and region codes for this dimension |

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:

```json theme={null}
{
  "advertiserId": "adv-globex",
  "qualified": false,
  "qualificationGaps": [
    {
      "dimension": "channels",
      "state": "no_overlap",
      "advertiserValues": ["ctv"],
      "sellerValues": ["display"]
    },
    {
      "dimension": "markets",
      "state": "no_overlap",
      "advertiserValues": ["FR", "DE"],
      "sellerValues": ["ZA"]
    }
  ]
}
```

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](https://docs.apostra.com/v3/media-partner-availability.md#when-matching-doesnt-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`:

| Value | Meaning |
| - | - |
| `active` | The media partner has made the account active, so it can be searched for this advertiser. |
| `pending` | The account is being set up and will resolve by itself. |
| `needs_attention` | The account may not resolve without you, an operator or the media partner. `requiredAction`, `failureReason` and `actionUrl` on the same entry say what is owed. |
| `null` | The advertiser does not match this media partner and owes it no setup, so no account is expected. |

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](https://docs.apostra.com/v3/identity-setup.md)).

`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](https://docs.apostra.com/v3/buyer-agents.md) 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 }`:

| State | The Media Partners page says | Meaning |
| - | - | - |
| `ready` | Ready | You can buy from this media partner. It says nothing about whether you have: live campaigns stay in the campaign counts. `nextStep` is `null`. |
| `needs_you` | Needs you | You must act. `nextStep.resolvedBy` is `buyer`. |
| `waiting` | Waiting on partner, or Waiting on Apostra | Nothing you can do fixes it. `nextStep.resolvedBy` is `provider` (the media partner or the platform it connects to) or `apostra`. |

`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.

| `action` | What it means |
| - | - |
| `connect` | The media partner needs your own login on its platform and you have not completed one. |
| `reconnect` | Your connection stopped working, Apostra needs you to sign in again to read your ad accounts, or your sign-in lacks a permission that buying needs. |
| `approve_billing` | Billing needs a decision: accept direct billing, choose payment terms, or add or fix the media billing entity in Plan & Billing. |
| `use_live_advertiser` | The seller cannot serve this sandbox advertiser. Use a live advertiser to buy from this seller. |
| `finish_advertiser_setup` | The advertiser's account at the media partner is not finished. When `resolvedBy` is `buyer` you finish it, for example by completing the advertiser's setup, mapping its ad account, or setting a registrable operator domain. When it is `apostra` Apostra is setting the account up or fixing a setup problem; when it is `provider` the media partner has not opened the account, or has refused or closed it. |
| `resolve_payment` | The media partner needs payment settled. When `resolvedBy` is `provider` it refused the billing you asked for and only a commercial change with it can alter the answer. |

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](https://docs.apostra.com/v3/connection-account-discovery.md#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.

| `partnerKind` | What it sells |
| - | - |
| `platform` | An ad platform Apostra integrates with itself, such as Snap, Meta, Google, TikTok, Pinterest or Reddit. |
| `creator` | Creator channels. Apostra works it out from the channel handles and the agent's proof that it owns each channel. |
| `media` | Sites, apps or other properties. |

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](https://docs.apostra.com/v3/property-claims.md)), 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.

## 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](https://docs.apostra.com/v3/tool-reference.md#seller-and-product-filters).

* **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](https://docs.apostra.com/v3/media-partner-availability.md#what-a-media-partner-sells-platform-creator-or-media)).
  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](https://docs.apostra.com/v3/property-claims.md#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](https://docs.apostra.com/v3/count-with-search.md).

```json theme={null}
{
  "kind": "seller",
  "groupBy": "selected",
  "filter": { "partnerStatus": ["ACTIVE", "NEEDS_CONNECTION", "AVAILABLE"] }
}
```

```json theme={null}
{
  "objects": {
    "kind": "seller",
    "groupBy": "selected",
    "total": 1240,
    "groups": [
      { "value": "false", "count": 1100 },
      { "value": "true", "count": 140 }
    ],
    "truncated": false
  }
}
```

| `groupBy` | Groups |
| - | - |
| `selected` | `"true"` for media partners in your list and `"false"` for the rest. |
| `partnerKind` | `platform`, `media`, or `null` for a media partner with no kind (see [What a media partner sells](https://docs.apostra.com/v3/media-partner-availability.md#what-a-media-partner-sells-platform-creator-or-media)). No media partner reads `creator` yet, so there is no `creator` group. |
| `channel` | An AdCP channel, such as `display` or `ctv`. The counts overlap: see below. |
| `region` | An ISO country code, such as `US`. The counts overlap: see below. |

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](https://docs.apostra.com/v3/media-partner-availability.md#find-media-partners-with-search):
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.

```json theme={null}
{
  "objects": {
    "kind": "seller",
    "groupBy": "channel",
    "total": 120,
    "groups": [
      { "value": "display", "count": 95 },
      { "value": "ctv", "count": 41 }
    ],
    "truncated": false,
    "overlapping": true
  }
}
```

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 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.

| Input | What it does |
| - | - |
| `filter` | Five keys of the filter `search(kind: "seller")` takes: `selected`, `channel`, `region`, `partnerKind` and `sort`. Each means what it means in a search. More keys are added as the page acts on them. |
| `query` | The search text. As in a search, it covers every media partner you can see, in your list or not. |
| `tab` | With `sellerAccountId`: the tab of that media partner's page to open, one of `overview`, `offer`, `record`, `advertisers` or `settings`. Without `sellerAccountId` the call is refused. |

```json theme={null}
{
  "filter": {
    "selected": true,
    "region": "NL",
    "sort": "name"
  }
}
```

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.

```json theme={null}
{
  "selection": {
    "decision": "REMOVE",
    "sellerAccountIds": [2192, 2193, 2194]
  },
  "idempotencyKey": "remove-partners-2026-11-15-001"
}
```

The Media Partners page maps its actions to these decisions:

| On the page | `selection.decision` |
| - | - |
| Add, Always include | `ALWAYS_INCLUDE` |
| Never use | `ALWAYS_EXCLUDE` |
| Remove | `REMOVE` |

`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:

```json theme={null}
{
  "action": "bulk_updated",
  "change": "selection",
  "replayed": false,
  "sellers": [
    { "sellerAccountId": 2192, "action": "applied", "decision": "DEFAULT", "accountRequestsQueued": 0 },
    { "sellerAccountId": 2193, "action": "applied", "decision": "ALWAYS_EXCLUDE", "accountRequestsQueued": 0 },
    {
      "sellerAccountId": 2194,
      "action": "failed",
      "decision": null,
      "accountRequestsQueued": 0,
      "errors": [{ "code": "ACCESS_DENIED", "message": "Admin role required", "recovery": "correctable" }]
    }
  ],
  "accountRequestsQueued": 0
}
```

* `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](https://docs.apostra.com/v3/seller-first-booking.md).
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](https://docs.apostra.com/v2/concepts/asks.md#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.

## Related

* [Connect in five minutes](https://docs.apostra.com/v3/quickstart.md): connect a media partner and read its `seller` and `connection` objects.
* [Manage ads](https://docs.apostra.com/v3/manage-ads.md): set up advertisers and run campaigns across media partners.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.