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 identity, chosen a plan, 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.

Request access before you have an account

Every buyer door — bringing your own agent or code over MCP and the API, and working through Claude, ChatGPT or our own chat and UI — is in closed beta. You ask to join the waitlist, we review the request, and you complete terms and payment setup once you are let in. The self-serve journey described below is how getting in works once the waitlist comes off, not what you meet today.

Before account setup, Interchange may ask which Buyer or Seller product, country, channel, and supply path you need. Product readiness, market availability, and current supply are shown separately. If a product or market cell is not ready, you can record an email notification for that exact cell. If only Marketplace supply is missing, you can still continue, bring or connect supply, browse another cell, or record the notification. A waitlist submission records demand interest only. It does not create an account, confirm ownership of the email domain, or grant product access. It also does not put a future Account into a sandbox or pending lifecycle. When you continue signup, email verification and Organization proof resolve or create the Organization and Account; only ambiguous, conflicting, disputed, or risky claims require manual review. Choosing email notification records the exact disclosure text, locale, and version you accepted. It remains pending and cannot send email until your principal is verified. Before the intake is claimed, resubmitting the same email updates the exact scoped interest. After claim, sign in to update Organization interests; the public form will not modify reviewed evidence. If your organization already has an Interchange account, an invitation or an approved organization-access request remains the way you receive access. See Account Access & Signup for those paths.

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 and operator identity

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.

An account administrator must also confirm whether this buyer account represents the whole buying operator or a specific operating unit. A whole-operator account uses the operator domain alone. A specific unit adds a stable operator_unit.id, such as an established buying-seat, office, region, or team code. Review the other buyer accounts under the same operator before claiming the whole domain, and never use default, a temporary account name, a seller’s account ID, or an Interchange database ID as the unit ID.Open Buyer Setup through your connected agent, or use the buyer readiness API, to review and confirm this identity. See Buyer setup and go-live for the identity rules, existing-account migration behavior, and the distinction between account name, billing company, and stable unit ID.

Step 2: Choose a plan

Open Buyer Setup and continue to Plan & Billing to select the plan for this Buyer Account. Plan is an Account × product fact: it does not prove your Organization identity, accept Terms, provide payment authority, or guarantee that a particular market or supply source is available.

Step 3: 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 billing organization does not yet have an active contract, real operations remain blocked until an organization administrator accepts the latest Platform Service Agreement:

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, the Account is limited to the documented demo and onboarding surfaces. Real operations return HTTP 403 with an actionable setup error such as TOS_ACCEPTANCE_REQUIRED.If you enter through a bring-your-own buyer agent registration, every allowed V3 MCP tool result appends this warning while the registration is still in its signup sandbox or its customer-bound Organization has not accepted current Terms: “Demo/onboarding environment: demo data is synthetic and has no commercial effect. Do not rely on demo results for commercial decisions or present them as market data. Do not enter confidential or personal information. Full notice: https://interchange.io/agreements/demo-environment-notice”. MCP hosts also receive the same notice in _meta["scope3/demo-environment-warning"], with environment: "demo_onboarding", demoData: "synthetic", and commercialEffect: false, plus a machine-readable noticeUrl. Once current Terms are accepted, the warning stops and the Account’s normal capability checks govern each operation.

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 4: 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 5: 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 6: 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 7: 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 temporary billing compatibility metadata from BillingParty. It is never a storefront or execution type and does not determine campaign mode, BYOA, or protocol connectivity. 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 8: 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 9: 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. Direct Advertiser signup includes one account and one initial sandbox advertiser. It does not show organization hierarchy or an Add account control while that included account is in use. To add another account, use the contact action in the account selector or email support@scope3.com for a capacity upgrade. Once an upgrade is accepted, the control appears automatically; your organization, members, billing, and account history stay where they are. API attempts beyond the accepted account capacity fail consistently instead of creating a partial account. This limit is only for accounts in the organization. It does not limit how many advertisers, delegated advertisers, or connected advertising-platform accounts you can manage.

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. If the canonical Slack channel was archived, an account admin can select Slack again to restore it; the request confirms success only after the active channel binding is saved. People observed in that channel do not gain account access automatically; account admins review them in Communications and choose whether to add them to the account, keep them as channel guests, identify an external company, or disconnect the channel.

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.

Start here

Buy media

Sell media

Help and updates

Overview

Request access before you have an account

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

​Request access before you have an account

​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

Request access before you have an account

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