Skip to main content
POST
/
discovery
/
discover-products
Discover products
curl --request POST \
  --url https://api.interchange.io/api/v2/buyer/discovery/discover-products \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "advertiserId": 12345
}
'
{
  "discoveryId": "abc123-def456-ghi789",
  "productGroups": [
    {
      "groupId": "<string>",
      "groupName": "<string>",
      "products": [
        {
          "productId": "prod_123",
          "name": "Premium CTV Inventory - Sports",
          "channel": "ctv",
          "formatTypes": [
            "video",
            "15s",
            "30s"
          ],
          "cpm": 12.5,
          "salesAgentId": "<string>",
          "salesAgentName": "<string>",
          "storefrontId": "<string>",
          "storefrontName": "<string>",
          "supportedCampaignTypes": [],
          "description": "<string>",
          "deliveryType": "guaranteed",
          "briefRelevance": "<string>",
          "productCard": {
            "formatId": {
              "agentUrl": "<string>",
              "id": "<string>"
            },
            "manifest": {}
          },
          "productCardDetailed": {
            "formatId": {
              "agentUrl": "<string>",
              "id": "<string>"
            },
            "manifest": {}
          },
          "pricingOptions": [
            {
              "pricingOptionId": "<string>",
              "pricingModel": "<string>",
              "isFixed": true,
              "rate": 123,
              "floorPrice": 123,
              "fixedPrice": 123,
              "currency": "<string>",
              "priceGuidance": {
                "floor": 123,
                "p25": 123,
                "p50": 123,
                "p75": 123,
                "p90": 123
              }
            }
          ],
          "estimatedExposures": 0,
          "forecast": {},
          "bookability": "<string>",
          "publisherProperties": [
            {
              "publisherDomain": "<string>",
              "propertyType": "<string>",
              "name": "<string>",
              "selectionType": "<string>",
              "identifiers": [
                {}
              ]
            }
          ],
          "isSandbox": true,
          "formats": [
            {
              "agent_url": "<string>",
              "id": "<string>"
            }
          ],
          "formatOptions": [
            {
              "format_kind": "video_hosted",
              "format_option_id": "<string>",
              "display_name": "<string>",
              "params": {
                "containers": [
                  "mp4"
                ],
                "video_codecs": [
                  "h264"
                ],
                "audio_codecs": [
                  "aac"
                ]
              }
            }
          ]
        }
      ],
      "productCount": 4503599627370495,
      "totalProducts": 4503599627370495,
      "hasMoreProducts": true,
      "description": "<string>"
    }
  ],
  "totalGroups": 25,
  "hasMoreGroups": true,
  "summary": {
    "totalProducts": 150,
    "publishersCount": 25,
    "priceRange": {
      "min": 123,
      "max": 123,
      "avg": 123
    }
  },
  "budgetContext": {
    "sessionBudget": 123,
    "allocatedBudget": 123,
    "remainingBudget": 123,
    "budgetWarning": "<string>"
  },
  "proposals": [
    {
      "proposalId": "<string>",
      "name": "<string>",
      "allocations": [
        {
          "productId": "<string>",
          "allocationPercentage": 50,
          "pricingOptionId": "<string>",
          "rationale": "<string>",
          "sequence": 0,
          "tags": [
            "<string>"
          ]
        }
      ],
      "description": "<string>",
      "briefAlignment": "<string>",
      "salesAgentId": "<string>",
      "salesAgentName": "<string>",
      "storefrontId": "<string>",
      "storefrontName": "<string>",
      "supportedCampaignTypes": [],
      "expiresAt": "<string>",
      "totalBudgetGuidance": {
        "min": 123,
        "recommended": 123,
        "max": 123,
        "currency": "<string>"
      }
    }
  ],
  "agentResults": [
    {
      "agentId": "<string>",
      "agentName": "<string>",
      "success": true,
      "productCount": 4503599627370495,
      "error": "<string>",
      "skipReason": "<string>",
      "rawResponseData": "<unknown>",
      "debugLogs": [
        {
          "timestamp": "<string>",
          "type": "<string>",
          "message": "<string>",
          "request": {},
          "response": {}
        }
      ]
    }
  ],
  "refinementApplied": [
    {
      "id": "<string>",
      "notes": "<string>"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

API key or access token

Body

application/json

Request body for discovering products with optional auto-session creation

​
advertiserId
integer
required

Advertiser ID used to resolve BrandReference

Required range: x <= 9007199254740991
Example:

12345

​
discoveryId
string

Existing discovery ID. If not provided, a new discovery session is created.

Example:

"abc123-def456-ghi789"

​
campaignId
string

Campaign ID to seed discovery from. The campaign brief, flight dates, and budget are used as defaults (explicit request values take precedence).

Example:

"campaign_ea5e33dd-d65b-44c7-a3e8-8e1db1d137b4"

​
proposalCode
string

Storefront-issued proposal code (e.g. "PRP-XK4A29"). When set, the server short-circuits discovery and returns the seller's saved snapshot for this code. Caller's resolved operator must match the proposal's operator binding. Other discovery filters (brief, budget, channels, refine, etc.) are ignored.

Example:

"PRP-XK4A29"

​
channels
enum<string>[]

Channels to search (defaults to ["display", "olv", "ctv", "social"]). Accepts any AdCP MediaChannel value. "video" is an alias for "olv"; "audio" is an alias for "streaming_audio".

Available options:
display
Example:
["ctv", "display"]
​
countries
string[]

Countries to target (defaults to brand agent countries if not specified)

Maximum array length: 250
Pattern: ^[A-Z]{2}$
Example:
["US", "CA"]
​
brief
string

Natural language context for product search

Maximum string length: 5000
Example:

"Looking for premium video inventory targeting tech enthusiasts"

​
budget
number

Budget for the discovery

Required range: x > 0
Example:

50000

​
flightDates
object

Optional flight dates for availability filtering

​
publisherDomain
string

Filter products by publisher domain (exact domain component match)

Minimum string length: 1
Example:

"hulu"

​
pricingModel
enum<string>

Filter products by pricing model

Available options:
cpm,
vcpm,
cpc,
cpcv,
cpv,
cpp,
flat_rate
Example:

"cpm"

​
storefrontIds
integer[]

Filter discovery to these storefronts. Highly encouraged when the buyer wants results scoped to specific sellers — pass the IDs returned by list_storefronts. Combined with storefrontNames using OR logic. An empty array or omitted field both mean "no request-level filter" — if a campaignId is also provided and the campaign was created with storefrontIds, the campaign-level value is used in that case.

Maximum array length: 50
Required range: x <= 9007199254740991
Example:
[42, 57]
​
storefrontNames
string[]

Filter discovery to storefronts whose name matches one of these values (case-insensitive substring match). Use when the buyer mentions a seller by name. Combined with storefrontIds using OR logic. An empty array or omitted field both mean "no request-level filter" — campaign-level pinning is used in that case if available.

Maximum array length: 50
Maximum string length: 255
Example:
["Acme", "Acme Exchange"]
​
groupLimit
integer
default:10

Maximum number of product groups to return (default: 10, max: 10)

Required range: x <= 10
Example:

10

​
groupOffset
integer
default:0

Number of groups to skip for pagination

Required range: 0 <= x <= 9007199254740991
Example:

0

​
productsPerGroup
integer
default:10

Maximum products to return per group (default: 10, max: 15)

Required range: x <= 15
Example:

10

​
productOffset
integer
default:0

Number of products to skip within each group (default: 0, max: 1000)

Required range: 0 <= x <= 1000
Example:

5

​
debug
boolean

When true, includes detailed ADCP agent request/response debug logs in the response for troubleshooting

​
refine
object[]

Refinement instructions for iterating on previous discovery results. When provided, discoveryId is required.

Required array length: 1 - 100 elements

A refinement instruction for iterating on discovery results. Scoped to the overall request, a specific product, or a specific proposal.

Response

Discover products

Response from discovering products

​
discoveryId
string
required

Discovery ID

Example:

"abc123-def456-ghi789"

​
productGroups
object[]
required

Products grouped by publisher

​
totalGroups
integer
required

Total number of product groups available

Required range: 0 <= x <= 9007199254740991
Example:

25

​
hasMoreGroups
boolean
required

Whether more groups are available beyond those shown

​
summary
object
required

Summary statistics for discovered products

​
budgetContext
object

Budget context if budget was provided

​
proposals
object[]

Recommended media plans from sales agents (ADCP v3). Each proposal explains WHY certain products are recommended together and how budget should be allocated.

​
agentResults
object[]

Debug info for failed agents only. Only present when debug=true and at least one agent failed.

​
refinementApplied
object[]

Seller's response to each refinement instruction, matched by position to the request's refine array. Only present when refine was provided.