Buyer API Reference

Overview

The Scope3 Buyer API provides enhanced capabilities for brand advertisers to manage advertising campaigns through both REST and MCP (Model Context Protocol) interfaces. The API follows the SESOFI (Single Endpoint, Single Object, Full Intent) design principle:

Single Endpoint - One endpoint per high-level intent (update an advertiser, run a media buy, refine a discovery query)
Single Object - The endpoint accepts one object describing the full intent
Full Intent - That object carries every related decision so an agent can express what it wants in one call instead of orchestrating sub-resource updates

Connection Methods

REST API
MCP (AI Agents)

REST API (Recommended for traditional integrations)

Standard HTTP methods with JSON request/response bodies.Production:

https://api.interchange.io/api/v2/buyer

Staging:

https://api.staging.interchange.io/api/v2/buyer

Example:

curl https://api.interchange.io/api/v2/buyer/advertisers \
  -H "Authorization: Bearer scope3_your_api_key_here"

MCP (Model Context Protocol) for AI Agents

JSON-RPC 2.0 over HTTP POST with session management.Production:

https://api.interchange.io/mcp/buyer

Staging:

https://api.staging.interchange.io/mcp/buyer

Example:

curl -X POST https://api.interchange.io/mcp/buyer \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: your-uuid" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

OpenAPI Specification

Download the OpenAPI specification for SDK generation or API exploration:

Production: /api/v2/buyer/openapi.yaml
Staging: /api/v2/buyer/openapi.yaml

Authentication

All API requests require authentication using your Scope3 API key:

Authorization: Bearer scope3_your_api_key_here

Get API Key

Request API credentials to get started

REST API Endpoints

Advertisers

Core advertiser management endpoints. Following SESOFI, GET returns full advertiser data including all nested configuration.

Method	Endpoint	Description
GET	`/api/v2/buyer/advertisers`	List all advertisers
POST	`/api/v2/buyer/advertisers`	Create a new advertiser
GET	`/api/v2/buyer/advertisers/:id`	Get advertiser with full configuration
PUT	`/api/v2/buyer/advertisers/:id`	Update advertiser (partial or full)

Query Parameters for GET /advertisers:

includeAccounts - When true, includes linked partner accounts in each advertiser response (avoids N+1 calls to /accounts)
includeBrand - When true, includes resolved brand information (logos, colors, industry)
take / skip - Pagination

Example - List Advertisers with Accounts:

curl "https://api.interchange.io/api/v2/buyer/advertisers?includeAccounts=true" \
  -H "Authorization: Bearer scope3_your_api_key_here"

Example - Get Advertiser (returns EVERYTHING):

curl https://api.interchange.io/api/v2/buyer/advertisers/12345 \
  -H "Authorization: Bearer scope3_your_api_key_here"

Response includes:

Advertiser details (name, brand, sandbox, etc.)
Event sources
Test cohorts
Measurement configuration
Resolved brand (when includeBrand=true)

Example - Create Advertiser with Linked Accounts:

curl -X POST https://api.interchange.io/api/v2/buyer/advertisers \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "brand": "acme.com",
    "linkedAccounts": [
      {
        "storefrontId": 1,
        "sourceId": "src_main",
        "accountId": "acc_acme_pinnacle",
        "billingType": "brand"
      }
    ]
  }'

linkedAccounts field (available on create and update):

storefrontId - Storefront the source lives on
sourceId - Inventory source within the storefront whose account is being linked
accountId - Source-assigned account identifier (must come from GET /accounts/available)
billingType - Billing arrangement type (e.g. "brand", "agency")

On update, existing linked accounts are not removed — only new ones are added.

Event Sources

Register the channels (pixels, SDKs, CRM exports, MMPs) that send conversion events for an advertiser. Events sent against an unregistered event_source_id are rejected, so configure sources before turning on a pixel or feed.

Method	Endpoint	Description
GET	`/api/v2/buyer/advertisers/:advertiserId/event-sources`	List event sources
POST	`/api/v2/buyer/advertisers/:advertiserId/event-sources/sync`	Upsert event sources (ADCP-spec sync)

Example - Sync event sources:

curl -X POST https://api.interchange.io/api/v2/buyer/advertisers/12345/event-sources/sync \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "account": { "account_id": "12345" },
    "event_sources": [
      {
        "event_source_id": "website_pixel",
        "name": "Website Pixel",
        "event_types": ["purchase", "add_to_cart"],
        "allowed_domains": ["shop.example.com"]
      }
    ]
  }'

See the Measurement & Incrementality guide for the full event-source workflow, conversion ingestion, and incrementality test setup.

Test Cohorts

Manage test cohorts for A/B testing and incrementality measurement.

Method	Endpoint	Description
GET	`/api/v2/buyer/advertisers/:advertiserId/test-cohorts`	List all test cohorts
POST	`/api/v2/buyer/advertisers/:advertiserId/test-cohorts`	Create a test cohort
GET	`/api/v2/buyer/advertisers/:advertiserId/test-cohorts/:id`	Get a specific test cohort
PUT	`/api/v2/buyer/advertisers/:advertiserId/test-cohorts/:id`	Update a test cohort
DELETE	`/api/v2/buyer/advertisers/:advertiserId/test-cohorts/:id`	Delete a test cohort

Example - Create Test Cohort:

curl -X POST https://api.interchange.io/api/v2/buyer/advertisers/12345/test-cohorts \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "West Coast Treatment Group",
    "cohortType": "geographic",
    "role": "TREATMENT",
    "definition": { "type": "zip_code", "zips": ["94103", "97201", "98101"] },
    "estimatedSize": 50000
  }'

Required fields: name, cohortType, definition. Optional: role (TREATMENT | CONTROL, default TREATMENT), description, estimatedSize. The path param is :cohortId on the GET/PUT/DELETE routes.

Measurement Config

Configure measurement settings for an advertiser. This is a singleton resource per advertiser.

Method	Endpoint	Description
GET	`/api/v2/buyer/advertisers/:advertiserId/measurement-config`	Get measurement configuration
PUT	`/api/v2/buyer/advertisers/:advertiserId/measurement-config`	Update measurement configuration

Example - Update Measurement Config:

curl -X PUT https://api.interchange.io/api/v2/buyer/advertisers/12345/measurement-config \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mmmEnabled": true,
    "mmmConfig": { "provider": "scope3", "reportingFrequency": "weekly" },
    "incrementalityTestingEnabled": false,
    "brandLiftEnabled": false
  }'

All fields are optional. Available top-level fields: mmmEnabled, mmmConfig, incrementalityTestingEnabled, brandLiftEnabled, settings (key-value blob for additional vendor-specific settings). See the Measurement & incrementality guide for the full configuration shape.

Campaigns

Method	Endpoint	Description
GET	`/api/v2/buyer/campaigns`	List all campaigns
POST	`/api/v2/buyer/campaigns`	Create a new campaign
GET	`/api/v2/buyer/campaigns/:id`	Get campaign details
PUT	`/api/v2/buyer/campaigns/:id`	Update campaign
POST	`/api/v2/buyer/campaigns/:id/execute`	Execute/launch campaign
POST	`/api/v2/buyer/campaigns/:id/pause`	Pause campaign

Creatives

Creatives are manifest-based and nested under campaigns rather than advertisers. The full lifecycle (formats, manifests, asset uploads) is documented in the Creative object guide.

Method	Endpoint	Description
GET	`/api/v2/buyer/formats`	List supported creative formats
POST	`/api/v2/buyer/campaigns/:campaignId/creatives/create`	Create a manifest-based creative
GET	`/api/v2/buyer/campaigns/:campaignId/creativeManifest`	List manifests on a campaign
GET	`/api/v2/buyer/campaigns/:campaignId/creatives/:creativeId`	Get a creative
PUT	`/api/v2/buyer/campaigns/:campaignId/creatives/:creativeId`	Update a creative
DELETE	`/api/v2/buyer/campaigns/:campaignId/creatives/:creativeId`	Delete a creative

Media Buys

View media buy execution status and delivery metrics.

Method	Endpoint	Description
GET	`/api/v2/buyer/advertisers/:advertiserId/media-buys`	List all media buys
GET	`/api/v2/buyer/advertisers/:advertiserId/media-buys/:id`	Get a specific media buy

Media Buy Statuses:

DRAFT - Initial state, not yet submitted
PENDING_APPROVAL - Submitted, awaiting approval
INPUT_REQUIRED - Additional information needed
ACTIVE - Currently running
PAUSED - Temporarily paused
COMPLETED - Successfully finished
FAILED - Execution failed
REJECTED - Not approved
ARCHIVED - Archived/deleted

Example - List Media Buys:

curl https://api.interchange.io/api/v2/buyer/advertisers/12345/media-buys \
  -H "Authorization: Bearer scope3_your_api_key_here"

Reporting

Access hierarchical reporting metrics for campaigns, media buys, and packages. The endpoint supports both summary and timeseries views, plus a CSV download mode.

Method	Endpoint	Description
GET	`/api/v2/buyer/reporting/metrics`	Get reporting metrics (summary, timeseries, or CSV download)

Query Parameters:

advertiserId - Filter by advertiser ID
campaignId - Filter by campaign ID
mediaBuyId - Filter by media buy ID
startDate / endDate - ISO 8601 dates
view - summary (default — hierarchical advertiser → campaign → media buy → package) or timeseries (rows by date)
download - Pass true to return a signed CSV download URL instead of JSON

Example - Get Reporting:

curl "https://api.interchange.io/api/v2/buyer/reporting/metrics?advertiserId=12345&startDate=2026-01-15&endDate=2026-01-21" \
  -H "Authorization: Bearer scope3_your_api_key_here"

Response (summary view):

{
  "data": {
    "advertisers": [
      {
        "advertiserId": "12345",
        "name": "Acme Corp",
        "totals": { "impressions": 325000, "spend": 2701.25, "clicks": 970 },
        "campaigns": [
          {
            "campaignId": "cmp_987",
            "totals": { "impressions": 200000, "spend": 1500.00 },
            "mediaBuys": [
              { "mediaBuyId": "mb_abc", "totals": { "impressions": 100000 }, "packages": [] }
            ]
          }
        ]
      }
    ],
    "totals": { "impressions": 325000, "spend": 2701.25, "clicks": 970 },
    "periodStart": "2026-01-15",
    "periodEnd": "2026-01-21"
  }
}

For event counts (conversion summary), see GET /api/v2/buyer/advertisers/:advertiserId/events/summary in the Reporting overview guide.

Source Accounts

Discover and link advertiser accounts on inventory sources (e.g. a DSP seat). The flow is: discover available accounts via GET .../accounts/available, then assign one to the advertiser via POST .../accounts.

Method	Endpoint	Description
GET	`/api/v2/buyer/advertisers/:advertiserId/accounts/available`	List accounts discovered on an inventory source
GET	`/api/v2/buyer/advertisers/:advertiserId/accounts`	List accounts linked to this advertiser
GET	`/api/v2/buyer/advertisers/:advertiserId/accounts/:accountId`	Get a single linked account
POST	`/api/v2/buyer/advertisers/:advertiserId/accounts`	Assign a discovered account to this advertiser

Query Parameters for GET .../accounts/available:

storefrontId (required) - Storefront the source lives on. Get from GET /api/v2/buyer/storefronts.
sourceId (required) - Inventory source within storefrontId whose accounts to list.
credentialId - ID of a specific registered credential to use for account discovery. Required when the customer has multiple credentials registered for this source. Use GET /api/v2/buyer/storefronts/credentials to list credentials and their IDs.
refresh - Set to true to re-fetch from the source; defaults to cached results

Example - Discover available accounts:

curl "https://api.interchange.io/api/v2/buyer/advertisers/12345/accounts/available?storefrontId=1&sourceId=src_main" \
  -H "Authorization: Bearer scope3_your_api_key_here"

Example - Assign an account:

curl -X POST https://api.interchange.io/api/v2/buyer/advertisers/12345/accounts \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "storefrontId": 1,
    "sourceId": "src_main",
    "accountId": "acc_acme_pinnacle"
  }'

Account fields (from source):

accountId - Source-assigned account identifier
name - Human-readable account name (e.g. "Acme c/o Pinnacle")
advertiser - Advertiser name as recorded by the source
billingProxy - Agency or proxy buying on behalf of the advertiser
house - Domain or house identifier
billing - Billing arrangement type (e.g. "brand")
sources - Array of { storefrontId, storefrontName, sourceId, sourceName } showing every storefront source through which this account is reachable

Storefronts

Browse storefronts (publisher inventory marketplaces) and register credentials per inventory source. See the Storefront object guide for the full data model and end-to-end flow.

Method	Endpoint	Description
GET	`/api/v2/buyer/storefronts`	List storefronts (paginated)
GET	`/api/v2/buyer/storefronts/:storefrontId`	Get a single storefront
GET	`/api/v2/buyer/storefronts/discover`	Lightweight list (active + upcoming)
GET	`/api/v2/buyer/storefronts/interest`	Check your interest submission status
POST	`/api/v2/buyer/storefronts/interest`	Submit interest in upcoming storefronts
GET	`/api/v2/buyer/storefronts/credentials`	List your credentials across storefronts
POST	`/api/v2/buyer/storefronts/:storefrontId/sources/:sourceId/credentials`	Register credentials for a source
POST	`/api/v2/buyer/storefronts/:storefrontId/sources/:sourceId/accounts`	Register an account on a source

Query Parameters for GET /storefronts:

name - Case-insensitive partial match on storefront name
limit - 1..50 (default 20)
offset - Pagination offset (default 0)

Example - List Storefronts:

curl "https://api.interchange.io/api/v2/buyer/storefronts?limit=20" \
  -H "Authorization: Bearer scope3_your_api_key_here"

Example - Register an Account on a Storefront Source:

curl -X POST "https://api.interchange.io/api/v2/buyer/storefronts/acme-media/sources/acme-sales-agent/accounts" \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "accountIdentifier": "acme-brand-account",
    "accountType": "brand"
  }'

The partner-agent response fields (requiresOperatorAuth, billingOptions, accountResolution) appear on the Sales Agents endpoints, not on storefronts — see the Sales Agents section below.

The advertiserId field has been removed from the register account body. Use the Partner Accounts endpoints to link accounts to specific advertisers after registration.

Catalogs

Manage product and offering catalogs that can be synced to partner platforms.

Method	Endpoint	Description
GET	`/api/v2/buyer/advertisers/:advertiserId/catalogs`	List catalogs
POST	`/api/v2/buyer/advertisers/:advertiserId/catalogs`	Create a catalog
GET	`/api/v2/buyer/advertisers/:advertiserId/catalogs/:catalogId`	Get a catalog
PUT	`/api/v2/buyer/advertisers/:advertiserId/catalogs/:catalogId`	Update a catalog
DELETE	`/api/v2/buyer/advertisers/:advertiserId/catalogs/:catalogId`	Archive a catalog (also archives all offerings)
POST	`/api/v2/buyer/advertisers/:advertiserId/catalogs/sync`	Sync catalogs to partner platforms

Supported catalog types: product, offering, hotel, flight, destination, home_listing, vehicle, job, local, retail, travel, education Example - Create a catalog:

curl -X POST https://api.interchange.io/api/v2/buyer/advertisers/12345/catalogs \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Products",
    "type": "product",
    "description": "Summer 2025 product catalog"
  }'

Example - Sync to partners:

curl -X POST https://api.interchange.io/api/v2/buyer/advertisers/12345/catalogs/sync \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerIds": ["premiumvideo_a1b2c3d4"]
  }'

Offerings

Manage individual offerings (products, listings, etc.) within a catalog.

Method	Endpoint	Description
GET	`/api/v2/buyer/advertisers/:advertiserId/catalogs/:catalogId/offerings`	List offerings in a catalog
POST	`/api/v2/buyer/advertisers/:advertiserId/catalogs/:catalogId/offerings`	Create an offering
GET	`/api/v2/buyer/advertisers/:advertiserId/catalogs/:catalogId/offerings/:offeringId`	Get an offering
PUT	`/api/v2/buyer/advertisers/:advertiserId/catalogs/:catalogId/offerings/:offeringId`	Update an offering
DELETE	`/api/v2/buyer/advertisers/:advertiserId/catalogs/:catalogId/offerings/:offeringId`	Archive an offering

Example - Create an offering:

curl -X POST https://api.interchange.io/api/v2/buyer/advertisers/12345/catalogs/cat_abc/offerings \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "offeringId": "sku_001",
    "title": "Wireless Headphones",
    "description": "Premium noise-cancelling headphones",
    "price": 299.99,
    "currency": "USD",
    "landingUrl": "https://example.com/products/headphones"
  }'

MCP Tools

The Buyer MCP server uses a generic tool pattern rather than individual tools per resource. AI agents interact with the full REST API surface through these tools:

Tool	Description
`health`	Health check to verify the API is reachable.
`accept_tos`	Accept the platform Terms of Service. Required before any write call if your customer hasn’t accepted yet — writes return `403 TOS_ACCEPTANCE_REQUIRED` until this runs.
`ask_about_capability`	Query the API documentation to look up correct endpoint paths, field names, and request schemas. Call this before `api_call` when unsure of the exact interface.
`api_call`	Authenticated HTTP proxy to any buyer REST endpoint. Supports all methods (GET, POST, PUT, DELETE) with full request/response passthrough.
`customer_switch`	Switch the active customer context. Available to any user with membership in more than one customer org; SuperAdmin users can switch to any customer.
`admin`	Platform-management operations (SuperAdmin only).

Required workflow for AI agents: Always call ask_about_capability first to retrieve accurate field names and schemas before calling api_call. Field names are camelCase (e.g. advertiserId, not advertiser_id).

Using `api_call`

The api_call tool proxies to any endpoint under /api/v2/buyer/. It handles authentication automatically. MCP Example - List Advertisers:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "api_call",
    "arguments": {
      "method": "GET",
      "path": "/api/v2/buyer/advertisers",
      "query": { "includeAccounts": true }
    }
  }
}

MCP Example - Create Advertiser:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "api_call",
    "arguments": {
      "method": "POST",
      "path": "/api/v2/buyer/advertisers",
      "body": {
        "name": "Acme Corp",
        "brand": "acme.com"
      }
    }
  }
}

MCP Example - Get Reporting:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "api_call",
    "arguments": {
      "method": "GET",
      "path": "/api/v2/buyer/reporting/metrics",
      "query": { "advertiserId": "12345", "startDate": "2026-01-15", "endDate": "2026-01-21" }
    }
  }
}

Supported Endpoint Families

The api_call tool allows access to:

Endpoint Family	Example Operations
`/api/v2/buyer/advertisers/*`	Advertiser CRUD, event sources, test cohorts, measurement config, accounts, catalogs, offerings
`/api/v2/buyer/campaigns/*`	Campaign CRUD, execute, pause
`/api/v2/buyer/discovery/*`	Product discovery and selection
`/api/v2/buyer/campaigns//creatives/`	Manifest-based creative lifecycle (nested under campaigns)
`/api/v2/buyer/media-buys/*`	View media buy status and delivery
`/api/v2/buyer/reporting/*`	Impressions, spend, clicks metrics
`/api/v2/buyer/sales-agents/*`	Partner agent discovery and account registration
`/api/v2/buyer/signals/*`	Audience signal listing

Response Format

All responses follow a consistent structure:

{
  "data": { ... },
  "error": null,
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Response:

{
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Advertiser not found"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Support

For technical support, contact us at support@scope3.com.

Buyer API

Documentation Index

​Buyer API Reference

​Overview

​Connection Methods

​REST API (Recommended for traditional integrations)

​MCP (Model Context Protocol) for AI Agents

​OpenAPI Specification

​Authentication

Get API Key

​REST API Endpoints

​Advertisers

​Event Sources

​Test Cohorts

​Measurement Config

​Campaigns

​Creatives

​Media Buys

​Reporting

​Source Accounts

​Storefronts

​Catalogs

​Offerings

​MCP Tools

​Using api_call

​Supported Endpoint Families

​Response Format

​Support

Buyer API Reference

Overview

Connection Methods

REST API (Recommended for traditional integrations)

MCP (Model Context Protocol) for AI Agents

OpenAPI Specification

Authentication

REST API Endpoints

Advertisers

Event Sources

Test Cohorts

Measurement Config

Campaigns

Creatives

Media Buys

Reporting

Source Accounts

Storefronts

Catalogs

Offerings

MCP Tools

Using `api_call`

Supported Endpoint Families

Response Format

Support