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:OpenAPI Specification
Download the OpenAPI specification for SDK generation or API exploration:- Production: /api/v2/buyer/openapi.yaml
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- Whentrue, includes linked partner accounts in each advertiser response (avoids N+1 calls to/accounts)includeBrand- Whentrue, includes resolved brand information (logos, colors, industry)take/skip- Pagination
- Advertiser details (name, brand, sandbox, etc.)
- Event sources
- Test cohorts
- Measurement configuration
- Resolved brand (when
includeBrand=true)
linkedAccounts field (available on create and update):
storefrontId- Storefront the source lives onsourceId- Inventory source within the storefront whose account is being linkedaccountId- Source-assigned account identifier (must come fromGET /accounts/available)billingType- Billing arrangement type (e.g."brand","agency")
Event Sources
Register the channels (pixels, SDKs, CRM exports, MMPs) that send conversion events for an advertiser. Events sent against an unregisteredevent_source_id are rejected, so configure sources before turning on a pixel or feed.
Example - Sync event sources:
Test Cohorts
Manage test cohorts for A/B testing and incrementality measurement.
Example - Create Test Cohort:
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:
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 includebudget_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 submittedPENDING_APPROVAL- Submitted, awaiting approvalINPUT_REQUIRED- Additional information neededACTIVE- Currently runningPAUSED- Temporarily pausedCOMPLETED- Successfully finishedFAILED- Execution failedREJECTED- Not approvedARCHIVED- Archived/deleted
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 IDcampaignId- Filter by campaign IDmediaBuyId- Filter by media buy IDstartDate/endDate- ISO 8601 datesview-summary(default — hierarchical advertiser → campaign → media buy → package) ortimeseries(rows by date)download- Passtrueto return a signed CSV download URL instead of JSON
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 viaGET .../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 fromGET /api/v2/buyer/storefronts.sourceId(required) - Inventory source withinstorefrontIdwhose 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. UseGET /api/v2/buyer/storefronts/credentialsto list credentials and their IDs.refresh- Set totrueto re-fetch from the source; defaults to cached results
accountId- Source-assigned account identifiername- Human-readable account name (e.g."Acme c/o Pinnacle")advertiser- Advertiser name as recorded by the sourcebillingProxy- Agency or proxy buying on behalf of the advertiserhouse- Domain or house identifierbilling- 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 namelimit- 1..50 (default 20)offset- Pagination offset (default 0)
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:
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 genericapi_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 throughapi_call.
To operate on a different account in the same MCP session, call the dedicated customer_switch MCP tool:
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:
Supported Endpoint Families
Theapi_call tool allows access to: