Buyer Onboarding

This guide walks you end-to-end from “I have an API key” to “my first campaign is live.” It is intended for agency teams, in-house brand marketers, and engineers building automated media-buying workflows on top of Scope3.

Overview

By the end of this guide you will have:

Confirmed your buyer account and accepted the platform Terms of Service.
Created an advertiser, linked to a brand identity.
Configured measurement and (optionally) registered event sources for performance optimization.
Run a discovery to find products that match your brief.
Created, executed, and monitored your first campaign.

Prefer to drive everything through an AI agent? You can do every step below by talking to a connected MCP agent (Claude, ChatGPT, Cursor) — the agent will call these endpoints for you. See the Quick Start for connector setup.

Prerequisites

Pick how you’ll authenticate

Pick one — you don’t need both.

OAuth (recommended for AI agents)

Connecting through Claude (Team/Enterprise/Desktop), ChatGPT MCP Connectors, or any OAuth-aware AI tool. Auth is handled automatically via the connector — no API key to manage. See Built for Agents for connector setup.

API key

Required only for CLI tools, Cursor, custom MCP/HTTP clients, or programmatic backend integrations. Generate at interchange.io/user-api-keys; keys start with scope3_. See Authentication for full details.

The rest of this guide shows REST curl examples with Authorization: Bearer $SCOPE3_API_KEY. If you’re using OAuth via Claude/ChatGPT, replace each step with the equivalent natural-language prompt — the connected agent will call the same endpoints for you.

Optional

SSO

If your organization uses SAML SSO, ask your admin to configure it via the SSO Setup guide before inviting team members.

Private storefront credentials

Some storefronts gate inventory behind per-source credentials (API key, OAuth, JWT). Register those at the storefront-source level — see the Storefront object guide for the walkthrough.

All REST examples in this guide use the buyer base URL:

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

End-to-End Flow

Step 1: Confirm your account

Verify the API key resolves to the account you expect. The current account is the one that will own the advertisers and campaigns you create.

curl -X GET "https://api.interchange.io/api/v2/accounts/current" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Response:

{
  "data": {
    "id": 1234,
    "company": "Acme Media",
    "name": "Acme Media",
    "role": "ADMIN"
  }
}

If your team is structured as a parent organization with sub-brands or sub-agencies, list every account you can switch into with GET /api/v2/accounts and switch using POST /api/v2/accounts/switch. All subsequent API calls are scoped to the active account.

Step 2: Accept the Terms of Service

Signed in via the web app? If you registered or signed in at interchange.io, you accepted ToS during that flow — skip this step and go straight to Step 3.

If you signed up with an API key directly (not via the web app) and your account record does not yet have an active contract, the API will block writes until the latest Platform Service Agreement is accepted. Accept it once per account:

curl -X POST "https://api.interchange.io/api/v2/accept-tos" \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "psaVersion": "v1.0"
  }'

Until ToS is accepted, write operations (create advertiser, create campaign, etc.) return HTTP 403 with error code TOS_ACCEPTANCE_REQUIRED. Read endpoints continue to work.

Discovering the current psaVersion: use the psaVersion returned in the TOS_ACCEPTANCE_REQUIRED error response from any blocked write, or check the most recent agreement posted at scope3.com.

Step 3: Create an advertiser

An advertiser is the top-level container for campaigns. It carries brand identity, default optimization mode, and (optionally) UTM parameters and frequency caps that flow down to its campaigns.

curl -X POST "https://api.interchange.io/api/v2/buyer/advertisers" \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "description": "Global advertising account for Acme Corporation",
    "brand": "acme.com",
    "optimizationApplyMode": "MANUAL",
    "sandbox": false
  }'

const res = await fetch(
  'https://api.interchange.io/api/v2/buyer/advertisers',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SCOPE3_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Acme Corp',
      brand: 'acme.com',
      optimizationApplyMode: 'MANUAL',
      sandbox: false,
    }),
  },
)
const { data: advertiser } = await res.json()

Key fields:

Field	Description
`name`	Display name for the advertiser (1–255 chars).
`brand`	Domain (e.g. `acme.com`) or full manifest URL. Identity is resolved from `/.well-known/brand.json` or the AdCP brand registry.
`optimizationApplyMode`	`AUTO` applies Scope3 AI optimizations automatically; `MANUAL` requires approval. Defaults to `MANUAL`.
`sandbox`	When `true`, all downstream ADCP calls run against sandbox-flagged accounts — no real spend. Immutable after creation.
`linkedAccounts`	Optional partner-platform accounts to link at creation (e.g. Snap, Google).
`utmConfig`	Default UTM parameters appended to landing-page redirects.
`frequencyCaps`	Buyer-side frequency caps Scope3 enforces across publishers.

Building automation? Set sandbox: true for your first end-to-end run so nothing hits real exchanges or wallets.

Step 4: Configure measurement (recommended)

Measurement configuration lives on the advertiser and is shared across all of its campaigns. You can opt into MMM, incrementality testing, brand lift, and other measurement programs.

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

To optimize campaigns against your own conversion events, register one or more event sources for the advertiser. This pushes ADCP-spec event source definitions into Scope3:

curl -X POST "https://api.interchange.io/api/v2/buyer/advertisers/12345/event-sources/sync" \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account": { "account_id": "12345" },
    "event_sources": [
      {
        "event_source_id": "website_pixel",
        "name": "Acme Web Pixel",
        "event_types": ["page_view", "add_to_cart", "purchase"],
        "allowed_domains": ["acme.com", "shop.acme.com"]
      },
      {
        "event_source_id": "crm_uploads",
        "name": "Acme CRM Uploads",
        "event_types": ["purchase", "lead"]
      }
    ]
  }'

Each event source must include a buyer-assigned event_source_id (1–255 chars). You’ll reference it later when sending conversion events via the Conversion API.

Once registered, an event source can be referenced from a campaign’s performanceConfig.optimizationGoals to drive bid optimization.

Full conversion-tagging and measurement setup is covered in the Measurement guide.

Step 5: Discover products

Discovery turns a natural-language brief and budget into a session of candidate products from every reachable sales agent.

curl -X POST "https://api.interchange.io/api/v2/buyer/discovery/discover-products" \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "advertiserId": "12345",
    "brief": "Premium CTV inventory targeting tech enthusiasts in the US",
    "budget": 50000,
    "flightDates": {
      "startDate": "2026-05-01T00:00:00Z",
      "endDate": "2026-05-31T23:59:59Z"
    },
    "channels": ["ctv", "video"],
    "countries": ["US"]
  }'

The response contains a discoveryId (e.g. disc_abc123), grouped products (e.g. prod_xyz789), agent results, and (optionally) curated proposals you can apply directly to a campaign.

Discovery is iterative — call POST /api/v2/buyer/discovery/:id/discover-products again with refine to narrow results, or use POST /api/v2/buyer/discovery/:id/apply-proposal to load a curated set.

The full discovery workflow — refinement, proposals, manual product selection — is covered in the Discovery guide.

Step 6: Create your first campaign

A campaign references an advertiser and a (preselected) discovery session. The minimum required fields are advertiserId, name, flightDates, and budget. The legacy routingType field is not a campaign input; Interchange derives it per media buy as compatibility metadata for the current execution path. It does not determine campaign mode, BYOA, protocol connectivity, or settlement. See the Campaign guide for details.

curl -X POST "https://api.interchange.io/api/v2/buyer/campaigns" \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "advertiserId": "12345",
    "name": "Acme Q2 CTV Launch",
    "flightDates": {
      "startDate": "2026-05-01T00:00:00Z",
      "endDate": "2026-05-31T23:59:59Z"
    },
    "budget": { "total": 50000, "currency": "USD" },
    "constraints": {
      "channels": ["ctv", "video"],
      "geo_countries": ["US"]
    },
    "discoveryId": "disc_abc123",
    "productIds": ["prod_xyz789"]
  }'

Response:

{
  "data": {
    "campaign": {
      "campaignId": "cmp_67890",
      "advertiserId": "12345",
      "name": "Acme Q2 CTV Launch",
      "status": "DRAFT"
    }
  }
}

Capture the campaignId from the response — we’ll use this cmp_* id in Steps 7–8.Key choices:

Field	Notes
`discoveryId` + `productIds`	Attach a discovery session and pre-select products. Optional but typical.
`performanceConfig`	Add optimization goals tied to event sources or pacing metrics.
`pacingPeriods`	Time-based pacing schedule with weight or fixed budget per period.
`audienceConfig`	Target / suppress audience IDs from the signals catalog.

The campaign is created in DRAFT status — nothing has been sent to a sales agent yet.

Step 7: Add creatives

Before a campaign can launch, every product format selected on the campaign needs at least one creative that satisfies it. The creative endpoint is a single multipart request — a JSON metadata field plus one or more files parts:

curl -X POST "https://api.interchange.io/api/v2/buyer/campaigns/cmp_67890/creatives/create" \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F 'metadata={"name":"Hero 30s CTV Spot","template_id":"video_standard","url_asset":{"url":"https://acme.com/promo","url_type":"CLICKTHROUGH"},"assets":[{"filename":"hero-30s.mp4","asset_type":"VIDEO","label":"main_video"}]};type=application/json' \
  -F "files=@hero-30s.mp4"

Inspecting GET /api/v2/buyer/campaigns/:id returns a creativeFormats summary so you can see which formats are still missing creatives before launch. See the Creatives guide for the full lifecycle.

Step 8: Execute the campaign

Executing a campaign sends media-buy requests to every selected sales agent and transitions the campaign from DRAFT to ACTIVE.

curl -X POST "https://api.interchange.io/api/v2/buyer/campaigns/cmp_67890/execute" \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "data": {
    "campaignId": "cmp_67890",
    "previousStatus": "DRAFT",
    "newStatus": "ACTIVE",
    "success": true
  }
}

If any media buys fail at the sales agent, success is false and errors[] lists the per-buy failures. After fixing the issue, you can re-run POST /api/v2/buyer/campaigns/:id/execute while the campaign is still DRAFT. The retry submits the same surviving DRAFT media buy; it does not rebuild the buy from discovery or discard per-buy creatives, flight dates, pacing, or optimization goals you changed after the failure.

execute and reactivate are different endpoints. Use POST /api/v2/buyer/campaigns/:id/execute to launch a DRAFT (or COMPLETED) campaign. To resume a PAUSED campaign, use POST /api/v2/buyer/campaigns/:id/reactivate instead.

Need to pass debug: true? Add { "debug": true } to the body — Scope3 returns extra trace data from each upstream agent.

Monitoring

Once a campaign is ACTIVE, poll the live status of its media buys:

curl -X GET "https://api.interchange.io/api/v2/buyer/campaigns/cmp_67890/media-buy-status" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

The response includes per-media-buy status pulled directly from each ADCP sales agent, plus a list of agents queried and any status changes detected on this poll. Pair this with the Reporting overview for delivery, spend, and performance metrics. To pause a running campaign:

curl -X POST "https://api.interchange.io/api/v2/buyer/campaigns/cmp_67890/pause" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Sandbox Testing

Set sandbox: true when creating an advertiser to run the entire flow above with no real spend. All downstream ADCP calls are tagged sandbox and routed to test accounts on the storefront’s inventory sources. Sandbox mode is immutable after creation — you cannot promote a sandbox advertiser to production. See Sandbox mode for the full sandbox capability matrix.

Adding an Account to Your Organization [#adding-a-child-account]

Organizations with multiple brands or business units can split into an organization with accounts under it. An organization admin provisions a new account via POST /api/v2/accounts/create-child (or “Add account” in the UI). The new account inherits the organization’s governing agreement; it does not accept separate account-level Terms of Service.

How inherited acceptance works

If the parent organization has an active governing agreement, the new account inherits it and is ready to use. If the organization has no active agreement, the account is blocked with it. A direct ADMIN of the parent organization can accept the current ToS on behalf of the organization while scoped to either the organization or one of its accounts.

What the response tells you

Account and user-info responses include flags the UI uses to gate the experience when the organization has no active governing agreement:

{
  "data": {
    "customer": { "id": 9101, "company": "..." },
    "showTosBox": true,
    "canAcceptTos": false,
    "organizationContractMissing": true,
    ...
  }
}

showTosBox: true — the parent organization has no active governing agreement.
canAcceptTos: false — the currently authenticated user is not allowed to accept because they are not a direct parent-organization admin. The UI shows a blocking notice in this state.
organizationContractMissing: true — the account is blocked by its parent organization’s missing governing agreement.

What the organization admin can still do

While the organization sits unaccepted, its admins can:

Invite members of the account. The customer_member_invite MCP tool and the member-management cluster are exempted from the ToS guard so onboarding flows can complete.
Configure the support channel. /api/v2/customer/communication-channel and the notification-preferences surfaces are exempted for the same reason.

Other surfaces stay gated until a direct parent-organization admin accepts ToS.

How acceptance happens

If the intended signer is only an account member, invite them to the parent organization as ADMIN. Pending organization invitations remain available before ToS acceptance. After they accept the invitation, their /auth/me response carries canAcceptTos: true; POST /api/v2/accept-tos writes the organization’s active contract and unblocks every account that inherits it.

Next Steps

Advertiser object

Linked accounts, brand resolution, UTM templates, and frequency caps.

Campaign object

Performance config, pacing, audience targeting, and execution lifecycle.

Discovery workflow

Briefs, refinement, proposals, and product selection.

Measurement workflow

Conversion events, MMM, incrementality, and brand lift.

Reporting

Delivery, pacing, spend, and performance reporting endpoints.

Storefronts

Browse storefronts and connect credentials per inventory source.

Getting Started

Advertisers

Campaigns

Product Discovery

Webhooks

Creatives

Signals & Brand

Audiences & Inventory

Measurement & Conversions

Reporting & Activity

Planning & Governance

Connections

Account & Billing

Overview

Prerequisites

Pick how you’ll authenticate

OAuth (recommended for AI agents)

API key

Optional

End-to-End Flow

Monitoring

Sandbox Testing

Adding an Account to Your Organization [#adding-a-child-account]

How inherited acceptance works

What the response tells you

What the organization admin can still do

How acceptance happens

Next Steps

Advertiser object

Campaign object

Discovery workflow

Measurement workflow

Reporting

Storefronts

​Overview

​Prerequisites

​Pick how you’ll authenticate

OAuth (recommended for AI agents)

API key

​Optional

​End-to-End Flow

​Monitoring

​Sandbox Testing

​Adding an Account to Your Organization [#adding-a-child-account]

​How inherited acceptance works

​What the response tells you

​What the organization admin can still do

​How acceptance happens

​Next Steps

Advertiser object

Campaign object

Discovery workflow

Measurement workflow

Reporting

Storefronts

Overview

Prerequisites

Pick how you’ll authenticate

Optional

End-to-End Flow

Monitoring

Sandbox Testing

Adding an Account to Your Organization [#adding-a-child-account]

How inherited acceptance works

What the response tells you

What the organization admin can still do

How acceptance happens

Next Steps