> ## Documentation Index > Fetch the complete documentation index at: https://docs.interchange.io/llms.txt > Use this file to discover all available pages before exploring further. # Buyer Onboarding > End-to-end setup guide for agencies and brands buying media through Interchange API 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](/v2/quickstart) for connector setup. *** ## Request access before you have an account If the Interchange signup form asks you to request access, tell us your work email, company, intended markets and channels, timing, and whether you want a campaign management system or plan to use an AI agent. If you choose an agent, we also ask which agent you plan to use. These details help the commercial team route your request without asking for a committed media budget. Selecting an agent records your preferred setup for review; it does not connect or provision the agent automatically. Submitting the form places your request in review. It does **not** create an account, confirm ownership of the email domain, or grant product access. A commercial reviewer must verify and claim the request before Interchange links the submitted organization and contact to its records. The team will follow up with the next step; you do not need to submit the form again. 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](/v2/setup/account-access) for those paths. *** ## Prerequisites ### Pick how you'll authenticate Pick **one** — you don't need both. 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](/v2/setup/built-for-agents) for connector setup. Required only for CLI tools, Cursor, custom MCP/HTTP clients, or programmatic backend integrations. Generate at [interchange.io/user-api-keys](https://interchange.io/user-api-keys); keys start with `scope3_`. See [Authentication](/v2/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 If your organization uses SAML SSO, ask your admin to configure it via the [SSO Setup guide](/v2/setup/sso-setup) before inviting team members. Some storefronts gate inventory behind per-source credentials (API key, OAuth, JWT). Register those at the storefront-source level — see the [Storefront object guide](/v2/object-guides/storefront#registering-credentials-per-source) 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 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. ```bash theme={null} curl -X GET "https://api.interchange.io/api/v2/accounts/current" \ -H "Authorization: Bearer $SCOPE3_API_KEY" ``` Response: ```json theme={null} { "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. **Signed in via the web app?** If you registered or signed in at [interchange.io](https://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: ```bash theme={null} 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](https://scope3.com). 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. ```bash curl theme={null} 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 }' ``` ```typescript TypeScript theme={null} 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. 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. ```bash theme={null} 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: ```bash theme={null} 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](/v2/integrations/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](/v2/guides/measurement-incrementality). Discovery turns a natural-language brief and budget into a session of candidate products from every reachable sales agent. ```bash theme={null} 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](/v2/guides/discovery). 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](/v2/object-guides/campaign) for details. ```bash theme={null} 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: ```json theme={null} { "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. 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: ```bash theme={null} 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](/v2/object-guides/creative) for the full lifecycle. Executing a campaign sends media-buy requests to every selected sales agent and transitions the campaign from `DRAFT` to `ACTIVE`. ```bash theme={null} 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: ```json theme={null} { "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: ```bash theme={null} 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](/v2/guides/reporting-overview) for delivery, spend, and performance metrics. To pause a running campaign: ```bash theme={null} 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](/v2/features/sandbox) 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: ```json theme={null} { "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 Linked accounts, brand resolution, UTM templates, and frequency caps. Performance config, pacing, audience targeting, and execution lifecycle. Briefs, refinement, proposals, and product selection. Conversion events, MMM, incrementality, and brand lift. Delivery, pacing, spend, and performance reporting endpoints. Browse storefronts and connect credentials per inventory source.