Skip to main content

​
Overview

A buyer property list is a buyer-owned include or exclude set of domains, apps, or CTV identifiers. An include list asks the seller to run only on those properties; an exclude list asks the seller never to run on them. The property list reaches the seller as an ADCP PropertyListReference, and only when the seller declares in its AdCP capabilities that it applies that kind of list (see Which sellers receive a reference). Where the reference appears depends on the request: Exclude lists are never sent at discovery; Apostra applies them on its own side when it selects products. For discovery, the include reference travels in the get_products filters:
For campaign or media-buy execution, the references appear in each package’s targeting overlay:

​
Which sellers receive a reference

Apostra sends a package reference only to a seller that declares, in its AdCP get_adcp_capabilities response, that it applies that kind of list: The two declarations are independent: declaring property_list does not opt a seller into exclude lists. For a product sold through an Apostra storefront, the seller that applies the list is the sales agent behind the storefront, so Apostra reads that agent’s declaration, not the storefront’s own. Apostra uses the AdCP capabilities it last refreshed for that agent, and the storefront passes both references to the agent unchanged. To receive references, declare property_list or property_list_exclude in your own sales agent’s capabilities. Managed sales agents and platform adapters publish no such declaration, so they receive no references. If Apostra cannot read the declaration, it sends no reference. The same rule applies when a list changes: a seller that does not declare a reference’s dimension receives the update without that reference. Whatever the seller declares, Apostra also checks the buyer’s exclude lists against each product’s disclosed properties before it sends a buy.

​
One reference per field

A buyer can set lists on an advertiser and on an individual campaign. The seller does not receive each list separately. Apostra sends one reference per field that combines every list in effect for the package: When only one list is in effect, list_id is that list’s numeric id, such as "42". When several lists are combined, list_id names them all, such as "include:41,42" or "exclude:43,44", and the resolved list is named “Combined inclusion lists” or “Combined exclusion lists”. Treat list_id as an opaque string: resolve it exactly as received, percent-encoding it in the URL path. Each auth_token is signed for its own list_id and opens no other list.

​
What the seller’s agent does

When your sales agent receives a property-list reference, it resolves the list from the buyer’s agent URL:
For Apostra buyer lists, that path is mounted at the app root:
The response uses the ADCP property-list shape:
Agents should cache the resolved list until cache_valid_until (24 hours after resolved_at), then re-fetch if the buy or update still needs it. The endpoint always serves the list’s current content, so a re-fetch picks up any change the buyer made. When the buyer changes a list, Apostra also sends update_media_buy to every active media buy that uses it, carrying the reference in effect on each package. The list_id stays the same when only the list’s content changed, so treat that update as a signal to re-fetch the list rather than relying on the cached copy. Large lists can be paginated. Pass max_results and follow pagination.cursor while pagination.has_more is true. Cache each resolved page until cache_valid_until. pagination.total_count is reported on the first page of a single list only; a combined list omits it.

​
What it means operationally

Today, Apostra forwards the property-list references and provides the resolution endpoint. The seller decides how to honor them. Common seller-side outcomes: Do not treat a buyer property list as automatic ad-server enforcement. If the seller has not configured a way to execute that subset, the honest answer is that the storefront can see the buyer’s requested properties but must decide seller-side whether it can run against them.

​
How this relates to coverage

Coverage and buyer property lists answer different questions. For network sellers, publisher_properties usually comes from adagents.json authorized coverage. A buyer property list is the buyer’s requested subset inside or across seller coverage.

Property lists

Buyer-side list creation, validation, and resolution.

Publisher properties and coverage

How buyers see the publisher domains a product covers.

Custom targeting and properties

How seller-managed GAM key-values relate to site lists.

Ad-server signals

Browse GAM targeting and create signals.