Skip to main content

​
Overview

A property list is a named, advertiser-scoped collection of domains used to shape where a brand’s media runs. Lists carry a purpose of either include (only buy on these properties) or exclude (never buy on these properties). Once created, lists are linked to the brand’s targeting profile and flow into every product discovery and media buy as part of the ADCP target_overlay. Property lists are a buyer-curated concept. They are owned by your advertiser, validated against the AAO property registry, and pushed to sales agents as a PropertyListReference that the agent resolves on demand.

Include lists

Restrict targeting to a hand-picked allow-list (e.g., a curated PMP of premium publishers).

Exclude lists

Block specific domains across all of an advertiser’s campaigns (e.g., a brand-safety blocklist).

​
Concept

Each list stores a set of domains that are normalized, deduped, and resolved through two systems:
  1. AAO registry — the cross-publisher Ad Context registry used to confirm a domain is a real, identified property.
  2. Local property catalog — Scope3’s mapping of domains to targetable Property records used by sales agents.
Submitted domains land in one of three buckets, surfaced in every create/update response as a resolutionSummary:
BucketMeaningTargets?
resolvedCountMapped to a local Property recordYes
registeredCountKnown to AAO but no local property yetNot yet — will become targetable as catalog catches up
unresolvedCountNot found anywhereNo — silently skipped
A single list can hold up to 100,000 domains per request. The service chunks large inputs server-side against the AAO registry (which itself caps at 10,000 domains per call) and returns a single resource with the full resolution summary.

​
Endpoints

All buyer endpoints below are mounted under https://api.agentic.scope3.com/api/buyer. The GET /lists/:listId resolution endpoint is mounted at the app root (no /api/buyer or /api/storefront prefix) per ADCP convention.
MethodPathPurpose
GET/api/buyer/advertisers/:advertiserId/property-listsList lists for an advertiser
POST/api/buyer/advertisers/:advertiserId/property-listsCreate a list
GET/api/buyer/advertisers/:advertiserId/property-lists/:listIdGet one list
PUT/api/buyer/advertisers/:advertiserId/property-lists/:listIdReplace a list’s domains and/or name
DELETE/api/buyer/advertisers/:advertiserId/property-lists/:listIdArchive a list
POST/api/buyer/property-lists/checkValidate a candidate domain set without creating a list
GET/lists/:listIdHigh-cardinality public read used by sales agents (HMAC token auth, mounted at app root)
All propertyList-returning responses use the { propertyList } wrapper. List endpoints return { propertyLists, total }.

​
How to use

​
Create an include list

curl -X POST 'https://api.agentic.scope3.com/api/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": ["nytimes.com", "bbc.co.uk", "cnn.com"],
    "filters": {
      "channels_any": ["display", "olv"],
      "countries_all": ["GB"]
    }
  }'
Response: 
{
  "propertyList": {
    "listId": "42",
    "name": "Q1 UK Premium",
    "purpose": "include",
    "domains": ["nytimes.com", "bbc.co.uk", "cnn.com"],
    "unresolvedDomains": [],
    "registeredDomains": [],
    "propertyCount": 3,
    "resolutionSummary": {
      "totalRequested": 3,
      "resolvedCount": 3,
      "registeredCount": 0,
      "unresolvedCount": 0,
      "resolutionRate": 1
    },
    "filters": { "channels_any": ["display", "olv"], "countries_all": ["GB"] },
    "createdAt": "2026-04-25T10:30:00.000Z",
    "updatedAt": "2026-04-25T10:30:00.000Z"
  }
}
resolutionSummary is only returned on create and update. GET and list responses contain only the resolved domains because the stored list drops unresolved entries.

​
Update a list

A PUT replaces the full domain set. Active media buys that reference this list are then notified — see Cascade behavior. 
curl -X PUT 'https://api.agentic.scope3.com/api/buyer/advertisers/12345/property-lists/42' \
  -H 'Authorization: Bearer scope3_<your_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "domains": ["nytimes.com", "bbc.co.uk", "theguardian.com"]
  }'
The update response includes both resolutionSummary and cascadeSummary.

​
Validate before you commit

Use POST /api/buyer/property-lists/check to lint a candidate domain list against curation rules without creating anything: 
curl -X POST 'https://api.agentic.scope3.com/api/buyer/property-lists/check' \
  -H 'Authorization: Bearer scope3_<your_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{ "domains": ["nytimes.com", "duplicate.com", "duplicate.com", "bad-domain"] }'
The response groups domains into action buckets:
BucketMeaning
okClean — safe to include
modifyCanonicalized (e.g., WWW.example.com → example.com)
removeDrop — duplicate or blocked
assessManual review recommended
A summary block gives counts and a reportId (plus reportIds[] for chunked inputs) you can reference later.

​
Cascade behavior

When you PUT an include list, every active media buy whose advertiser references the list is notified via ADCP update_media_buy so the sales agent can refresh its cached property set. The update response surfaces this with a cascadeSummary: 
{
  "cascadeSummary": {
    "totalMediaBuys": 4,
    "updatedCount": 3,
    "failedCount": 1
  }
}
The cascade is best-effort and applies to include lists only — the ADCP target_overlay.property_list reference carries include semantics. Cascade failures do not roll back the list update; the database is the source of truth and per-media-buy errors are logged for retry.
Per-media-buy fan-out is bounded (concurrency 5) so a large advertiser cannot thunder a single sales agent.

​
Resolution endpoint

Sales agents resolve a PropertyListReference by calling GET https://api.agentic.scope3.com/lists/:listId with an HMAC bearer token that Scope3 mints when it embeds the reference in a request. This endpoint is mounted at the app root (no /api/buyer or /api/storefront prefix) per ADCP convention. The endpoint returns ADCP GetPropertyListResponse shape (not the standard { data, error, meta } envelope): 
{
  "list": { "list_id": "42", "name": "Q1 UK Premium" },
  "identifiers": [
    { "type": "domain", "value": "nytimes.com" },
    { "type": "domain", "value": "bbc.co.uk" }
  ],
  "resolved_at": "2026-04-25T10:30:00.000Z",
  "cache_valid_until": "2026-04-26T10:30:00.000Z"
}
Agents are expected to cache the response until cache_valid_until (24 h).

​
Best practices

  • Always inspect resolutionSummary. Any non-zero unresolvedCount indicates domains that will not target — surface them to the user before going live.
  • Prefer one large list over many small ones. A 100k-domain list is cheaper than 100 lists of 1k domains because each list creates its own SmartPropertyList link.
  • Use filters.channels_any to scope a list. Without it, the list applies across all of the brand’s targeting profiles. With it, you can keep display/OLV separate from CTV.
  • Treat updates as full replacements. PUT replaces the entire domain set; there is no incremental add/remove. Re-send the union you want stored.
  • Validate before bulk import. Run POST /api/buyer/property-lists/check on the raw input first, especially when assembling a list from spreadsheets or third-party feeds.
  • Avoid touching include lists during high-traffic windows. Cascading notifies every active media buy on the advertiser; schedule large updates for off-peak times when possible.

​
Limits

LimitValue
Domains per request (create or update)100,000
Domains per AAO registry call (auto-chunked)10,000
Cascade concurrency per update5 media buys at a time
List name length1–255 characters
Cache TTL on resolved list24 hours