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

# What a media partner sells: property claims and networks

> How Apostra reads which properties a media partner sells from each property's own adagents.json, what authorized, unverified and not authorized mean, how networks and their members are found, and how to dispute a status.

Many media partners can say they sell the same property. A publisher's sales
house, a rep firm, a network and a reseller can all claim it. Apostra does not
take their word for it. It reads what the property's own domain says, and
reports that.

## What a claim is

A **claim** is a property, shown as the domain a media partner registered, that
the media partner says it sells. Apostra decides the status of each claim from
the `adagents.json` file on the property's own domain, as Apostra last read it.
What a media partner says about itself never changes a status.

| Status | What it means |
| - | - |
| `authorized` | The property's `adagents.json` lists the media partner's agent, and that listing is in effect today. There is one claim for each listing in effect. |
| `not_authorized` | The file exists, Apostra read it completely, and it leaves the media partner's agent out, or lists it only outside the listing's dates. |
| `unverified` | The property's own domain cannot confirm the claim. The domain has no `adagents.json`, or Apostra has never read it, could not read it, or is waiting to read it again. The claim is the media partner's alone. |

A listing is in effect when today is on or after its `effective_from` and before
its `effective_until`. A listing with neither date is always in effect. A listing
that has expired, or has not started yet, stops counting on its own: the domain's
other listings, and their statuses, are unaffected. A date Apostra cannot parse
counts as outside the window.

An unread file is never a `not_authorized`. A file that was never read, failed to
read, or is waiting to be read again leaves the claim `unverified` until Apostra
reads it.

An `authorized` claim carries what the file states, exactly as AdCP names it:
`delegation_type`, `exclusive`, `countries` and `placement_ids`. A field the file
leaves out is left out of the claim too.

| `delegation_type` | What the file says |
| - | - |
| `direct` | The publisher treats this as a direct way to buy from it. |
| `delegated` | The agent is authorized to sell on the publisher's behalf. |
| `ad_network` | The inventory is sold as part of a network or package, not as the publisher's direct endpoint. |

## Read a media partner's claims

Every `seller` read, from `get` and from `search` with `kind: "seller"`,
carries `propertyClaims`:

* `byStatus` counts the claims as `authorized`, `unverified` and
  `not_authorized`.
* `authorizedByDelegationType` counts the authorized claims as `direct`,
  `delegated` and `ad_network`. A listing that states no `delegation_type`
  counts as authorized and under none of the three.

To list the claims, call `get` with `kind: "seller"`, the media partner's `id`
and `include: ["propertyClaims"]`. It returns at most 100, authorized first,
then unverified, then not authorized, each group in order of property domain.
`propertyClaimsOmitted` counts the claims the list leaves out. Each claim has
the property (`{ "type": "domain", "value": "nu.nl" }`), its `status`, and for an
authorized claim the file's own fields.

## Networks and their members

A media partner can be a **member** of a network. Apostra finds membership in the
properties' own files, and nobody types it in. A media partner is a member of a
network when a property's `adagents.json` authorizes the media partner directly
(`direct`) and authorizes the network as `delegated` or `ad_network`. An
unverified claim never makes a member.

* `memberCount` is how many members a media partner has.
* `memberOf` lists the seller Account ids of the networks a media partner belongs
  to.
* `search` with `kind: "seller"` and `filter: { "memberOf": <seller Account id> }`
  lists a network's members, page by page.

Only media partners a buyer can list count as members.

## Who can sell me this property, here

To find who can sell a property in the country you are buying in, call `search`
with `kind: "seller"` and both filters:

```json theme={null}
{
  "kind": "seller",
  "filter": {
    "property": { "type": "domain", "value": "nu.nl" },
    "country": "NL"
  }
}
```

The answer is every media partner whose claim to that property covers that
country, best first. Many media partners can hold claims to one property, so the
answer is a list and never a single owner.

* `property` is an AdCP property identifier. Apostra holds claims by domain, so
  only `{ "type": "domain", "value": "nu.nl" }` is answered. Any other type, such
  as `ios_bundle`, is refused with `UNSUPPORTED_FEATURE`, never answered with an
  empty list. The domain is matched exactly, in lower case, as the media partner
  registered it: `www.nu.nl` is a different domain from `nu.nl`.
* `country` is an ISO 3166-1 alpha-2 code, in capitals. Who can sell a property
  depends on where you buy it, so each filter needs the other: a `property`
  without a `country`, or a `country` without a `property`, is refused. To list
  media partners that sell in a country, use `filter.region`.
* The search reads every media partner listed on Apostra, whether or not it is in
  your list. Each result's `controlPlane.selection.selected` says which are. Add
  `filter.selected: true` to keep your own list, or `filter.transactable: true`
  to keep the media partners you can buy from through Apostra now. It combines
  with the other `search` filters.

Each result carries `propertyAccess`: the media partner's claim to that property,
as the property's own `adagents.json` states it, with its `rank`. It has the same
fields as a claim in `propertyClaims`, except that its `status` is never
`not_authorized`.

| `rank` | Who | What the file says |
| - | - | - |
| 1 | Exclusive for that country | Authorized, `exclusive: true`, for the whole property. For example, the property's sales house in that market. |
| 2 | Other direct sellers, sales houses and reps | Authorized, not exclusive, for the whole property. |
| 3 | Sellers limited to some placements | Authorized for some placements only. `placement_ids` names them. A listing that is exclusive for some placements only ranks here too. |
| 4 | Resellers | Authorized as `ad_network`, not exclusive, with no placement limit. |
| 5 | Unverified claims | The property has no `adagents.json`, or Apostra has not read it. The claim is the media partner's alone. |

A claim is offered for a country only when its listing covers it. A listing with
no `countries` covers every country. A listing with `countries` covers only
those, so an authorization limited to other countries does not match. A listing
outside its `effective_from` and `effective_until` dates does not count. A
`not_authorized` claim is never offered as a way to buy the property: it shows on
the media partner's own read instead. An unverified claim names no country, so it
is offered for any country, and it ranks last.

When a media partner has several listings for the property, `propertyAccess`
shows the one that ranks best for your country, the first in the file on a tie.

### The order of the results

The ranking is the default order whenever `filter.property` is set: rank 1 first,
then 2 to 5, and media partners of the same rank by name. Apostra ranks them, and
a client shows the order it receives.

* `filter.sort: "name"` replaces the ranking with A to Z across every rank. Each
  result still says its `rank`.
* `query` narrows the results by name. Within one rank the closest name match
  comes first, unless `filter.sort` is `name`.
* Pages follow the same order, and a `cursor` returned by a search in a different
  order is refused as an invalid cursor. Ask for the next page with the same
  filters, `query` and `sort`.
* `groupBy: "selected"` or `"partnerKind"` counts exactly the media partners the
  same filters list.

A property search stops with an error when the request is cancelled, and after
five seconds.

## If a status or a membership is wrong

The property's own file is the authority, so the fix starts there. A publisher who
wants a media partner to read `authorized` adds it to the `authorized_agents` list
in its `adagents.json` and keeps the file reachable. Apostra reads the new file the
next time it reads that domain, and the status follows.

If you think Apostra read a file wrongly, or a status does not match what the file
says today, tell Apostra through your usual contact. Staff review the dispute in
their supply review. A media partner that disagrees with its own status disputes it
the same way.


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