AdCP — Implementor FAQ

Common questions from teams building AdCP sales agents and integrations, with direct answers based on the specification.

Product Discovery

Q: Is hard targeting in a brief actually hard, and why use an overlay?

A: Yes. Sellers MUST apply explicit hard requirements even when they appear only in brief prose. Buyers should nevertheless put every fact with an AdCP representation in its structured field. targeting_overlay uses fewer tokens, is deterministic code rather than seller inference, and preserves exact semantics through forecasting, purchase, and readback. When a seller extracts hard targeting from the brief and the structured interpretation materially affects product eligibility, pricing, or forecasting, it MUST confirm that interpretation once in the discovery response’s targeting_resolution.brief_targeting. In other cases it SHOULD still confirm it as a best practice. This is especially useful for requests such as “US only, ages 18–44.” Absence of Product targeting resolution confirms an unchanged structured overlay for that product; absence of response-level confirmation does not confirm what was extracted from prose. Sellers do not repeat unchanged overlay values, which avoids echoing large inputs such as hundreds of postal codes.

Q: Does `get_products` require specific parameters like budget, dates, and objectives?

A: Use brief for objectives and semantic intent, filters for product characteristics, targeting_overlay for exact delivery constraints, and required_overlay_support for targeting dimensions that will be selected later. Dates and budget guidance may still be expressed in the brief or supported structured filter fields. For the AdCP 3.2 split lifecycle, use list_products for synchronous offer listing and request_proposals for brief-driven planning. Both share structured discovery criteria; stateful proposal creation requires an idempotency_key. Legacy get_products remains the 3.x compatibility facade. Example:

{
  "idempotency_key": "550e8400-e29b-41d4-a716-446655442078",
  "buying_mode": "brief",
  "brand": {
    "domain": "acmecorp.com"
  },
  "brief": "Tech startup needs display and video inventory to reach IT decision makers. Budget: $25K. Timeline: March 1-31. Objective: Lead generation with 2% conversion target."
}

Q: How do I request specific audience targeting in `get_products`?

A: Put semantic audience intent in brief, but put exact delivery constraints in targeting_overlay. Use required_overlay_support for a dimension whose concrete values will be selected on packages later. Filters select product characteristics and the legacy targeting-like filter fields are deprecated. Example:

{
  "brand": {
    "domain": "energydrink.com"
  },
  "brief": "Reach sports fans for an energy drink campaign",
  "targeting_overlay": {
    "demographics": {
      "age": { "min": 18, "max": 34, "include_unknown": false }
    },
    "geo_countries": ["US"]
  },
  "required_overlay_support": {
    "geo_metros": { "systems": ["nielsen_dma"] }
  }
}

The seller interprets the brief and must also account for any structured overlay in availability, pricing, and forecasts. If it cannot execute the overlay exactly, it either omits the product or returns sparse targeting_resolution.modifications; selecting that request-scoped product accepts the disclosed changes.

Q: What does `buying_mode: "wholesale"` mean? We don’t expose a wholesale product feed.

A: In wholesale mode, buyers are requesting baseline products available without publisher curation or proposal generation. This does not make filters wholesale-only. Filters are hard product constraints in brief, wholesale, and refine; wholesale only changes the curation, response-timing, and feed-versioning behavior. If you don’t offer a wholesale product feed, return an error:

{
  "message": "We require a campaign brief to recommend products. Please provide details about your campaign goals, audience, and objectives.",
  "products": []
}

If you do offer wholesale access, return products matching the provided filters (format types, delivery type, etc.).

Q: Should buyers call `list_creative_formats` before or after `get_products`?

A: Neither for a new AdCP 3.2 workflow. Sales-agent list_creative_formats is deprecated. Call get_products and read each product’s canonical format_options[]; those declarations express what that product can deliver in the current account and inventory context. If a creative must be produced, find a compatible creative agent through the registry and confirm its get_adcp_capabilities.creative.supported_formats[]. Select the matching agent-local capability_id when calling build_creative.

Policy Compliance

Q: How do publishers know if there’s an ad policy issue (alcohol, adult content, etc.)?

A: Publishers extract advertiser identity from the brand field:

Extract advertiser info from the brand’s brand.json (resolved via brand.domain)
Check what’s being promoted from the brief text
Apply policy rules based on your publisher policies
Return appropriate response:
- Allowed: Return products normally
- Blocked: Return empty products array with policy explanation
- Restricted: Indicate manual approval needed

Example blocked response:

{
  "message": "I'm unable to offer products for this campaign. Our publisher policy prohibits alcohol advertising without age verification capabilities.",
  "products": []
}

See Policy Compliance for complete implementation guidance.

Q: Is the advertiser’s name always shared?

A: Yes, the brand field is required in both get_products and create_media_buy. It provides the advertiser identity needed for:

Policy compliance checks
Business relationship management (KYC)
Billing and reporting

Brand references are simple:

{
  "brand": {
    "domain": "acmecorp.com"
  }
}

The brand’s brand.json (resolved from the domain) provides category and other identity data for automated policy filtering.

Schema and Fields

Q: Why is the `filters` parameter called an “object”?

A: Because it’s a nested JSON object with multiple optional fields:

{
  "filters": {
    "delivery_type": "guaranteed",
    "standard_formats_only": true,
    "is_fixed_price": true,
    "min_exposures": 10000
  }
}

It’s not a single filter—it’s a collection of filter criteria for product catalog search.

Q: What replaces `format_ids` and ad units?

A: AdCP uses protocol-agnostic terminology:

format_options: Product-bound canonical creative contracts, including kind and constraints
Ad units: Platform-specific terminology (such as a 300×250 banner placement)

Canonical declarations are portable across platforms. A publisher option can be referenced by {publisher_domain, format_option_id}; a creative agent separately assigns an agent-local capability_id to a producible contract. Match the declarations, not the identifiers.

Q: How do I specify what’s being promoted?

A: There are two mechanisms depending on the context:

Advertiser identity → brand.domain (required on get_products and create_media_buy, resolves via /.well-known/brand.json)
What’s being promoted → Described in the brief field for product discovery, or provided via a catalog on creatives

For product discovery:

{
  "brand": {
    "domain": "nike.com"
  },
  "brief": "Nike Air Max 2024 - latest innovation in cushioning technology targeting runners and fitness enthusiasts"
}

For catalog-driven creatives, reference a synced catalog:

test=false

{
  "creative_id": "product-carousel",
  "format_kind": "sponsored_placement",
  "assets": {
    "source_catalog": {
      "asset_type": "catalog",
      "catalog_id": "product-feed"
    }
  }
}

Brief Processing

Q: What if buyers provide incomplete briefs?

A: Publishers should request clarification when critical information is missing:

{
  "message": "I'd be happy to help find the right products for your campaign. To provide the best recommendations, could you share:\n\n• What's your campaign budget?\n• When do you want the campaign to run?\n• Which geographic markets are you targeting?",
  "products": []
}

This maintains a conversational, helpful approach while gathering needed context.

Q: Should we always ask for clarification or just return products?

A: It depends on your publisher strategy:

High-touch approach: Request clarification for incomplete briefs, engage conversationally
Self-service approach: Return best-guess products based on available information

Both are valid. Consider your target buyer personas and automation level.

Workflow and Integration

Q: When should `brand` be required vs optional?

A: According to the current spec:

Required in both get_products AND create_media_buy

Best practice: Always require it. Policy checking should happen during discovery, not at purchase time.

Q: Can buyers cache product responses?

A: Products represent inventory availability which changes over time. Recommendations:

Brief-based discovery: Don’t cache—products are contextually matched to the brief
Standard catalog: Can cache for short periods (5-15 minutes) if your catalog is stable
Product details: Cache product_id mappings but revalidate availability before purchase

Q: How do we handle large product catalogs (1000+ products)?

A: Use property_tags instead of full properties arrays:

{
  "product_id": "local_radio_midwest",
  "property_tags": ["local_radio", "midwest"],
  "format_options": [
    { "format_kind": "audio_hosted", "params": { "duration_ms_exact": 30000 } }
  ]
}

Buyers can discover the agent’s portfolio via get_adcp_capabilities, which returns the publisher domains and primary channels the agent represents. This keeps responses lightweight while maintaining full validation capability.

Testing and Validation

Q: How do we test policy compliance?

A: Create test cases with known restricted categories:

// Test blocked category
const response = await get_products({
  idempotency_key: "550e8400-e29b-41d4-a716-446655442051",
  buying_mode: "brief",
  brand: {
    domain: "test-alcohol.example.com"
  },
  brief: "Promote our new craft beer"
});

assert(response.products.length === 0);
assert(response.message.includes("policy"));

Q: What should we test in integration testing?

A: Key scenarios to cover:

No brief + filters → Standard catalog
Brief provided → AI-matched products with brief_relevance
Blocked advertiser → Policy error
Incomplete brief → Clarification request
No products match → Helpful alternative suggestions
Format filtering → Only matching formats returned

Common Pitfalls

Q: Why aren’t my format filters working?

A: In AdCP 3.2, filter on canonical format kinds or exact format-option references:

{
  "filters": {
    "format_kinds": ["video_hosted"],
    "format_option_refs": [
      {
        "scope": "publisher",
        "publisher_domain": "streamhaus.example",
        "format_option_id": "preroll_30s"
      }
    ]
  }
}

Q: Why do my products not include `brief_relevance`?

A: brief_relevance is only included when a brief parameter is provided. Standard catalog requests (no brief) don’t include this field since products aren’t contextually matched.

Q: Should I validate authorization in `get_products`?

A: Yes! Buyer agents must validate sales agent authorization before purchasing:

Get properties from products (or resolve property_tags)
Fetch /.well-known/adagents.json from each publisher_domain
Verify the sales agent URL appears in authorized_agents
Reject products from unauthorized agents

See Authorization Validation for complete requirements.

Terminology

Q: What’s the difference between “product” and “package”?

Product: A sellable unit of inventory from the publisher (returned by get_products)
Package: A buyer’s selection from available products, sent in create_media_buy

Products describe what’s available. Packages describe what you’re buying.

Q: What’s the difference between “delivery” and “distribution”?

Delivery type: "guaranteed" vs "non_guaranteed" (whether impressions are guaranteed)
Distribution: How creatives are distributed to ad servers (covered by creative agents, not media buying)

Q: What’s “TMP” / “Trusted Match Protocol”?

A: The Trusted Match Protocol (TMP) is AdCP’s real-time execution layer. It determines which pre-negotiated packages activate at impression time using two structurally separated operations: Context Match (content relevance, no user identity) and Identity Match (user eligibility, no page context). The publisher joins both responses locally. TMP enables cross-publisher frequency capping, brand suitability, and audience targeting across web, mobile, CTV, AI assistants, and retail media. You may also see references to AXE (Agentic eXecution Engine) — that was TMP’s predecessor. Existing AXE integrations still work, but new implementations should use TMP. See AXE documentation for legacy reference.

Need More Help?

If your question isn’t answered here:

Check the Task Reference for detailed API documentation
Review Brief Expectations for discovery guidance
See Media Products for product model details
Open a GitHub issue for specification clarifications

This FAQ is updated regularly based on implementer feedback.

​Product Discovery

​Q: Is hard targeting in a brief actually hard, and why use an overlay?

​Q: Does get_products require specific parameters like budget, dates, and objectives?

​Q: How do I request specific audience targeting in get_products?

​Q: What does buying_mode: "wholesale" mean? We don’t expose a wholesale product feed.

​Q: Should buyers call list_creative_formats before or after get_products?

​Policy Compliance

​Q: How do publishers know if there’s an ad policy issue (alcohol, adult content, etc.)?

​Q: Is the advertiser’s name always shared?

​Schema and Fields

​Q: Why is the filters parameter called an “object”?

​Q: What replaces format_ids and ad units?

​Q: How do I specify what’s being promoted?

​Brief Processing

​Q: What if buyers provide incomplete briefs?

​Q: Should we always ask for clarification or just return products?

​Workflow and Integration

​Q: When should brand be required vs optional?

​Q: Can buyers cache product responses?

​Q: How do we handle large product catalogs (1000+ products)?

​Testing and Validation

​Q: How do we test policy compliance?

​Q: What should we test in integration testing?

​Common Pitfalls

​Q: Why aren’t my format filters working?

​Q: Why do my products not include brief_relevance?

​Q: Should I validate authorization in get_products?

​Terminology

​Q: What’s the difference between “product” and “package”?

​Q: What’s the difference between “delivery” and “distribution”?

​Q: What’s “TMP” / “Trusted Match Protocol”?

​Need More Help?