Skip to main content
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. 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.

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