Skip to main content

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

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

OpenAPI Specification

Download the OpenAPI specification for SDK generation or API exploration:

Authentication

All API requests require authentication using your Scope3 API key:

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. 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:
Example - Get Advertiser (returns EVERYTHING):
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:
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. Example - Sync event sources:
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. Example - Create Test Cohort:
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. Example - Update Measurement Config:
All fields are optional. Available top-level fields: mmmEnabled, mmmConfig, brandLiftEnabled, settings (key-value blob for additional vendor-specific settings). See the Measurement & incrementality guide for the full configuration shape.

Campaigns


Product discovery

See Get products across storefronts for progressive polling and qualified product identity.

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. For a creative sent through sync_creatives, each platform_links entry names the connected agent and may include its provider creative ID, latest sync state, approval state, and UTC sync timestamp. Use that linkage to reconcile the saved campaign creative with the object created on the platform. The field is optional for unsynced and historical creatives.

Media Buys

View media buy execution status and delivery metrics. Media buy and package budgets are gross (fee-inclusive) — reads include budget_denomination: "gross" and a read-only budget_breakdown showing the media/fee split at the fee terms locked when the buy was created (see Budgets and fees). Reduce budgets through the campaign update endpoint: when lowering budget.total below the live allocation, include the mediaBuys[] package reductions in the same atomic request. 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:

Reporting

Access hierarchical reporting metrics for campaigns, media buys, and packages. The endpoint supports both summary and timeseries views, plus a CSV download mode. 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:
Response (summary view):
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. 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 account 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:
Example - Assign an account:
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. 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:
Example - Register an Account on a Storefront Source:
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. Supported catalog types: product, offering, hotel, flight, destination, home_listing, vehicle, job, local, retail, travel, education Example - Create a catalog:
Example - Sync to partners:

Offerings

Manage individual offerings (products, listings, etc.) within a catalog. Example - Create an offering:

MCP Tools

The Buyer MCP server exposes dedicated tools for session-level actions and a generic api_call tool for REST operations. Use the dedicated MCP tool when one exists. Use api_call for buyer REST operations that do not have a more specific tool. Every api_call requires a named operation; the legacy raw method + endpoint form is no longer supported and is rejected.
Required workflow for AI agents: Choose the most specific MCP tool first. For account context, call customer_switch directly instead of routing through api_call. For REST operations, call ask_about_capability first when unsure of the exact interface, then call api_call with an operation name. Field names are camelCase (e.g. advertiserId, not advertiser_id).

Switch Account

Account switching is session state. It is not a per-call REST parameter and is not available through api_call. To operate on a different account in the same MCP session, call the dedicated customer_switch MCP tool:
After switching, retry the original api_call without customerId in params or body. If the target account is not available to the current MCP session, re-authenticate with that account’s credentials.

Using api_call

The api_call tool dispatches a named buyer operation. It handles authentication automatically and derives the HTTP method and endpoint from the operation, so you never write a URL. Pass params (query), pathParams, and body as the operation requires. MCP Example - List Advertisers:
MCP Example - Create Advertiser:
MCP Example - Get Reporting:

Supported Endpoint Families

The api_call tool allows access to:

Response Format

All responses follow a consistent structure:
Error Response:

Support

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