Property Lists

​

Overview

​

How lists are enforced

• Include lists are sent as filters.property_list during discovery when a sales agent declares either media_buy.features.property_list_filtering: true or media_buy.execution.targeting.property_list. A targeting_overlay.property_list reference is sent on media-buy packages only when the seller declares that it applies the list, and what counts depends on the AdCP release the seller speaks:
  • AdCP 3.2: the seller declares media_buy.execution.targeting.property_list. property_list_filtering there means discovery filtering only, so it does not make Apostra send the reference.
  • AdCP 3.0 and 3.1: the seller declares media_buy.features.property_list_filtering: true, which those releases define as honoring the list in get_products and in targeting_overlay, its adcp.supported_versions includes 3.0 or 3.1, and the product sets property_targeting_allowed: true. A product that does not allow property targeting is all or nothing, so the list cannot narrow it.
  Sellers without the relevant declaration do not receive the reference.
• Apostra-managed sales agents on Google Ad Manager do not take list references. For their products, Apostra sends both kinds of list as the agent’s property signal instead (see route 2 below).
• Exclude lists are not sent in get_products: AdCP discovery filters do not define property_list_exclude. They remain enforced on the buyer side during discovery and are sent as targeting_overlay.property_list_exclude on media-buy packages only when a sales agent declares media_buy.execution.targeting.property_list_exclude support. When an advertiser links multiple exclusion catalogs, the seller receives one reference that resolves to their combined, deduplicated identifiers. Apostra also enforces the list on the buyer’s side: products whose stored property identifiers match the advertiser’s exclusion list are filtered out of product discovery results, and execution rejects conflicting selections. Discovery reports the number removed in excludedProductCount, per-storefront counts in excludedProductCountsByStorefront, and bounded product details in excludedProductsByStorefront; each detail contains the product ID, name, and matching domains plus typed identifiers. Canonical get_products reports the same total as ext.interchange.excluded_product_count and each seller row carries excluded_product_count plus bounded excluded_products. The domains are the intersection of that seller product and the buyer’s own list, not the buyer’s complete list. When an exclusion empties a completed result, the response guidance says how many products from how many sellers were removed because they included excluded properties instead of calling the result a lack of matching inventory. A legacy candidate without seller identity is included in the total but not assigned to a seller row, so the guidance reports the removed-product count without inventing a seller count. When a seller declares property_list_exclude support, Apostra sends the exclusion list with the package and the seller removes matching properties within the product. Executing a campaign rejects a matching product only when its seller cannot enforce the exclusion list. It also rejects a product with no listed properties when that seller cannot enforce the list, because Apostra cannot prove where the product will run. Matching uses the typed identifiers the current property-membership model stores: domain, subdomain, ios_bundle, android_package, apple_tv_bundle, bundle_id, apple_app_store_id, google_play_id, roku_store_id, roku_channel_id, fire_tv_asin, fire_tv_app_id, amazon_app_store_id, samsung_app_id, lg_channel_id, and vizio_app_id. Identifier values are exact after normalisation: domains, iOS bundles, and Apple TV bundles are lowercased; Android packages, generic bundles, store IDs, and channel IDs keep their case. Products can declare every AdCP identifier type, but DOOH venue and podcast list entries are not stored by this property-list model yet, so they do not match an exclusion list at selection time.
• Products sold through an Apostra storefront take the declaration of the sales agent behind the storefront, not the storefront’s own. The storefront passes both references to that sales agent unchanged. Apostra reads the agent’s declaration from the AdCP capabilities it last refreshed for it, so a seller declares property_list or property_list_exclude in its own sales agent’s capabilities. Managed sales agents and platform adapters publish no such declaration, so they don’t receive references.
• A list reference you set on a package yourself (property_list, property_list_exclude, collection_list or collection_list_exclude in a package’s targetingOverlay) is sent only to a seller that declares that exact field under media_buy.execution.targeting. A collection-list reference also needs the product to allow collection targeting (collection_targeting_allowed: true); AdCP treats a product without it as a bundle. If the seller does not declare the field, executing the media buy, or updating a media buy the seller already holds, fails with a validation error that names the package, the field and the seller, and nothing is sent. A seller that does not declare a field is not obliged to apply the list, so sending it anyway could let the buy run without it. Remove the reference from the package, or choose products whose seller declares the field. If Apostra cannot read the seller’s declaration, the request fails with a retryable error instead.

​

Every list must be enforceable

1. The seller applies the list. The seller declares support for the list in its targeting capabilities (property_list for include lists, property_list_exclude for exclusion lists), or the product itself declares property_list_exclude in its overlay_support. An AdCP 3.0 or 3.1 seller declares include-list support with property_list_filtering instead, as described above; those releases have no exclusion list. Apostra sends the list reference with the buy. For a product sold through an Apostra storefront, the declaration that counts is the sales agent’s behind the storefront, as described above; it is the same declaration that decides which references the buy carries. The reference covers every list that applies: exclusion lists are combined, and the advertiser’s include list is combined with the campaign’s own.
2. Apostra sends the list as the seller’s property signals. This applies to products sold through an Apostra-managed sales agent whose ad server is Google Ad Manager and whose product offers the agent’s property signals. These are system-managed signals, one per ad-server key that identifies a site (for example property_domain); buyers are never offered them directly. Apostra reads the sites and apps the seller is authorized to sell and finds the ones on the list. Each one must have a value on one of those keys: a site’s value is its domain unless the seller has mapped it to a different value, and an app has a value only through the seller’s own mapping. Apostra then sends those values in the package’s signal_targeting_groups, alongside any signal targeting the buy already has. An exclusion list goes in one none group (the line item does not run on those sites), with an entry for each key it needs. An include list goes in one any group on a single key (the line item runs only on those sites), so the listed sites must share a key. The route does not apply if any listed site or app has no value, if a value is longer than 40 characters (Google Ad Manager’s limit; values are never shortened), if the listed sites of an include list share no key, if the product does not offer the property signals, or if one list needs more than 100 values. The values are computed from the sites and apps the seller is authorized to sell when the buy launches. If the list changes, or the seller authorizes a listed site afterwards, the values the buy was sent stop matching what Apostra computes now. Apostra checks this when you change a list and on its schedule, and updates the running buy with the new values instead of pausing it. It pauses the buy if the seller refuses the update, or does not confirm one that tightens the list (see When a live buy is paused).
3. Apostra can prove the product satisfies the list. Apostra knows every site and app the product can run on, and none of them is on an exclusion list (or, for include lists, all of them are on every one). Each entry in the product’s publisher_properties must either name a specific site or app with its own identifiers, or name a publisher with a selector that Apostra can resolve (see below).

​

Concept

​

Identifier types

​

Use with a V3 MCP agent

​

Property scores

{
  "advertiserId": "123",
  "name": "Spektre scores",
  "purpose": "include",
  "appliesToAllCampaigns": false,
  "identifiers": [
    {
      "type": "domain",
      "value": "site-a.nl",
      "features": {
        "spektre_aspi": { "value": 94, "measured_at": "2026-10-11T00:00:00Z" }
      }
    }
  ]
}

• Feature ids are yours. Name them after the provider (spektre_aspi). An id that starts with registry: is reserved by AdCP and refused. An identifier can carry up to 20 features, and one save up to 100,000 scores in total.
• Each score is an AdCP property feature value: value (a number, a string or a boolean) and optionally unit, confidence, measured_at, expires_at and methodology_version. measured_at and expires_at are ISO 8601 date-times. A value is limited to 2,048 bytes. AdCP’s free-form details and ext objects are stored with the value but are neither applied nor returned by get.
• Scores belong to your account, not the list. A property has one score per feature, whichever list names it. A later save replaces the value for that feature and property, and Apostra keeps the earlier value as history. Saving a value that has not changed adds no history, so you can save the whole score list again every day.
• Scores are saved before the list. If the list is then refused, the scores stay saved, and sending the same call again is safe: the scores are replaced in place and the list is created once.
• Saving scores does not need the list to be applied anywhere: save a list with appliesToAllCampaigns: false to keep scores without changing any campaign. Archiving a list does not delete scores.
• get(kind: "property_list") returns your scores beside each identifier it lists, as saved. A value past its expires_at is still shown, so check that field; it no longer counts when a list is resolved. A check (check: true) never saves scores and refuses features.

{
  "advertiserId": "123",
  "name": "ASPI 80 to 90",
  "purpose": "include",
  "appliesToAllCampaigns": false,
  "filters": {
    "feature_requirements": [
      { "feature_id": "spektre_aspi", "min_value": 80, "max_value": 90 }
    ]
  }
}

• A requirement is judged once you have saved a score for its feature. Until then it is not applied, so a floor saved before your scores cannot empty a list. The save response tells you when a requirement reads a feature with no saved score.
• A list with filters and no identifiers resolves to every property you have scored that meets the requirements. The example above is the whole list. A brand floor is an exclude list with "max_value": 19.9. Because such a list covers only properties you have scored, it never blocks a property you have not scored; to block one, list it by identifier.
• A list with identifiers and filters resolves to the identifiers that meet the requirements. An identifier with no live score for the requirement’s feature is removed unless if_not_covered is include, so an exclude list that must also block its unscored identifiers needs if_not_covered: "include".
• Edit the filters later. Save the list again with its propertyListId and filters. The new filters replace the old ones (filters: null removes them), and a list with no identifiers must keep at least one feature_requirements entry. channels_any cannot change after creation, because it chose which of the advertiser’s list slots took the list.
• A score or filter change that changes what a list resolves to is a list change. Saving the filters, or saving a changed score for a feature a list’s requirements read, pushes the list to the active media buys that use it, the same way editing its identifiers does, and the save response’s cascadeSummary counts the buys across all the lists that were pushed. A score that only changes metadata such as measured_at is not a change. A score save pushes every affected list inside the request. After 60 seconds it starts no further push and cancels the ones that have not reached a seller; a push already sent to a seller cannot be recalled, so it is allowed a few seconds to settle and is reported as pending. The save response’s cascadeSummary names the lists whose push finished in pushedListIds and the lists cancelled or not started in leftToRecheckListIds. A list left to the re-check is not a failure: the scheduled re-check of live buys compares each live buy with the lists as they now resolve and acts on any that are out of date, on its next run, and the counts cover only the pushes that finished. A score reaching its expires_at changes what a list resolves to at the time a seller next fetches it, without a push.
• What a seller sees. The hosted list a seller fetches carries identifiers only, never scores. It reflects your scores as of the fetch; a seller that has cached the list sees a score change after its cache expires, at most 24 hours later. A scored list does not report total_count.
• Exclusion checks (discovery and launch) read the same scores, so a floor list keeps scored properties below it out of a buy.

​

Campaign lists

• campaignPropertyListId sets the campaign’s own include list.
• campaignPropertyListExcludeId sets the campaign’s own exclude list.

• Exclusions add up. A property is excluded if the advertiser’s exclude lists or the campaign’s exclude list contain it. A campaign cannot remove an advertiser exclusion.
• Inclusions narrow. When both the advertiser and the campaign have an include list, a property must be on both.

​

Package lists

• Exclusions add up. The package’s exclude list is added to the advertiser’s and the campaign’s exclude lists.
• Inclusions narrow. The package’s include list is intersected with the advertiser’s and the campaign’s include lists, so a property must be on all of them.

• save_media_buy (V3) refuses it with the same error (cause not_hosted_by_us): save the list on the advertiser and use its id.
• The v2 batch create and update send it to the seller unchanged, as before, when no advertiser or campaign list applies to the same field, and the seller enforces it. When an advertiser or campaign list does apply to that field, the two cannot be combined, so the list that applies is sent in its place, as it always was. The response is unchanged; Apostra logs the package and list id that were not applied.

​

Endpoints

​

How to use

​

Create an include list

curl -X POST 'https://api.apostra.com/api/v2/buyer/advertisers/12345/property-lists' \
  -H 'Authorization: Bearer scope3_<your_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Q1 UK Premium",
    "purpose": "include",
    "domains": ["example-times.com", "example-press.co.uk", "example-news.com"],
    "filters": {
      "channels_any": ["display", "olv"],
      "countries_all": ["GB"]
    }
  }'

curl -X POST 'https://api.apostra.com/api/v2/buyer/advertisers/12345/property-lists' \
  -H 'Authorization: Bearer scope3_<your_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Cross-screen premium",
    "purpose": "include",
    "identifiers": [
      { "type": "domain", "value": "example-times.com" },
      { "type": "ios_bundle", "value": "com.exampletimes.ExampleTimes" },
      { "type": "android_package", "value": "com.exampletimes.android" },
      { "type": "apple_app_store_id", "value": "284862083" },
      { "type": "roku_store_id", "value": "12" }
    ]
  }'

{
  "propertyList": {
    "listId": "42",
    "name": "Cross-screen premium",
    "purpose": "include",
    "identifiers": [
      { "type": "domain", "value": "example-times.com" },
      { "type": "ios_bundle", "value": "com.exampletimes.ExampleTimes" },
      { "type": "android_package", "value": "com.exampletimes.android" }
    ],
    "unresolvedIdentifiers": [
      { "type": "apple_app_store_id", "value": "284862083" },
      { "type": "roku_store_id", "value": "12" }
    ],
    "registeredIdentifiers": [],
    "domains": ["example-times.com"],
    "unresolvedDomains": [],
    "registeredDomains": [],
    "propertyCount": 14,
    "resolutionSummary": {
      "totalRequested": 5,
      "resolvedCount": 3,
      "registeredCount": 0,
      "unresolvedCount": 2,
      "resolutionRate": 0.6
    },
    "createdAt": "2026-04-25T10:30:00.000Z",
    "updatedAt": "2026-04-25T10:30:00.000Z"
  }
}

• identifiers — typed {type, value}[] that are applied: every domain and subdomain, plus other identifiers AAO recognizes.
• unresolvedIdentifiers — submitted identifiers AAO does not recognize, other than domains. They are kept on the list but not applied.
• registeredIdentifiers — always empty; kept for compatibility.
• domains / unresolvedDomains / registeredDomains — convenience views of the above filtered to type: "domain". App identifiers are not in these.
• resolutionSummary — counts and resolutionRate (0..1) over the deduplicated, normalized input.

​

Update a list

curl -X PUT 'https://api.apostra.com/api/v2/buyer/advertisers/12345/property-lists/42' \
  -H 'Authorization: Bearer scope3_<your_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "identifiers": [
      { "type": "domain", "value": "example-times.com" },
      { "type": "ios_bundle", "value": "com.exampletimes.ExampleTimes" }
    ]
  }'

​

Validate before you commit

curl -X POST 'https://api.apostra.com/api/v2/buyer/property-lists/check' \
  -H 'Authorization: Bearer scope3_<your_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "identifiers": [
      { "type": "domain", "value": "example-times.com" },
      { "type": "domain", "value": "duplicate.com" },
      { "type": "domain", "value": "duplicate.com" },
      { "type": "ios_bundle", "value": "com.facebook.katana" }
    ]
  }'

​

Cascade behavior

• The reference changes when you create a list for the advertiser, archive, delete or restore one, or apply or clear a campaign’s list (V3 save_campaign, or POST /campaigns/:campaignId/property-lists). This covers include and exclude lists alike, whether the list is one of the advertiser’s lists or a campaign’s own list, and each campaign’s buys receive the combined reference in effect for that campaign (see Take property-list changes on live buys). Each checked buy whose sales agent declares support for the list gets the new reference through ADCP update_media_buy. A buy whose sales agent does not declare support gets nothing sent; that is not a failure, it only means another route has to enforce the list.
• The reference stays the same when you replace a list’s contents with PUT, but Apostra still sends update_media_buy to each seller that declares the field. This refreshes the seller’s hosted-list contents rather than waiting for its cache lifetime (see Limits). Buys that rely on Apostra proving their products clear are also checked against the new contents.

{
  "cascadeSummary": {
    "totalMediaBuys": 4,
    "updatedCount": 3,
    "failedCount": 1
  }
}

​

When a live buy is paused

• No route enforces one of its lists (reason: "list_not_enforceable"). Its sales agent does not apply the list, and Apostra cannot prove that every site and app its products can run on satisfies the list. Nothing is sent to the buy. The notification names each product, the list, and why. To restore the buy, remove the product, or resume it once its seller applies the list. A buy enforced through the seller’s property signals is paused the same way only when its values no longer match its lists and it cannot be updated in place (reason: "key_values_out_of_date", which happens when one product resolves to different values on different lines). Resuming it does not help: replace it with a new buy, which launches with current values.
• Its seller does not take the change (reason: "list_update_not_applied"). A change is not treated as applied until the seller confirms it. A short-lived failure (a timeout, a network error, a seller that answers “try again”) is retried a few times within about 15 seconds. A buy whose update still fails, because the seller rejects it, does not confirm it, or the update cannot be sent, is paused.

{
  "pendingCount": 1,
  "pendingSellerApproval": [
    { "mediaBuyId": "mb_789" }
  ]
}

{
  "cascadeSummary": {
    "totalMediaBuys": 4,
    "updatedCount": 2,
    "failedCount": 2,
    "sellerUpdatedCount": 2,
    "sellerFailedCount": 1,
    "enforcedByAnotherRouteCount": 0,
    "pausedCount": 1,
    "pauseFailedCount": 1,
    "actionRequired": [
      {
        "mediaBuyId": "mb_123",
        "outcome": "paused",
        "reason": "list_not_enforceable"
      },
      {
        "mediaBuyId": "mb_456",
        "outcome": "pause_failed",
        "reason": "list_update_not_applied",
        "pauseError": {
          "code": "SERVICE_UNAVAILABLE",
          "message": "Media buy mb_456 could not be paused upstream."
        }
      }
    ]
  }
}

​

Resolution endpoint

{
  "list": { "list_id": "42", "name": "Cross-screen premium" },
  "identifiers": [
    { "type": "domain", "value": "example-times.com" },
    { "type": "ios_bundle", "value": "com.exampletimes.ExampleTimes" },
    { "type": "android_package", "value": "com.exampletimes.android" }
  ],
  "resolved_at": "2026-04-25T10:30:00.000Z",
  "cache_valid_until": "2026-04-26T10:30:00.000Z"
}

​

Best practices

• Always inspect resolutionSummary. Any non-zero unresolvedCount indicates identifiers that will not target — surface them to the user before going live.
• Submit multiple identifier types for the same app. A mobile app is more reliably resolved when you include both its ios_bundle and android_package (and, where available, apple_app_store_id / google_play_id). Each is resolved independently against the AAO registry.
• Prefer one large list over many small ones. An advertiser has one all-campaigns list per purpose, and a campaign adds at most one of each, so put everything a brand needs excluded in one list.
• filters.channels_any does not scope where a list applies. It is AdCP’s channel filter, stored with the list. An all-campaigns list applies to every campaign in every channel; use a campaign’s own list for a narrower rule.
• Treat updates as full replacements. PUT replaces the entire identifier set; there is no incremental add/remove. Re-send the union you want stored.
• Validate before bulk import. Run POST /api/v2/buyer/property-lists/check on the raw input first, especially when assembling a list from spreadsheets or third-party feeds.
• Avoid list changes during high-traffic windows. Each one checks every active media buy on the advertiser, and a change of reference is sent to each of their sellers; schedule large changes for off-peak times when possible.

​

Limits

​

Related