Skip to main content
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 agentic.scope3.com/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

1

SSO

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

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.agentic.scope3.com/api/buyer

​
End-to-End Flow

1

Step 1: Confirm your account

Verify the API key resolves to the customer (account) you expect. The current account is the “seat” that will own the advertisers and campaigns you create.
curl -X GET "https://api.agentic.scope3.com/api/buyer/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/buyer/accounts and switch using POST /api/buyer/accounts/switch. All subsequent API calls are scoped to the active account.
2

Step 2: Accept the Terms of Service

If your customer 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 customer:
curl -X POST "https://api.agentic.scope3.com/api/buyer/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.
After acceptance, writes unblock immediately on the next request — no token refresh or re-auth is needed. If you signed up through the web app at agentic.scope3.com you have likely already accepted ToS and this step will be a no-op.
3

Step 3: Create an advertiser

An advertiser is the top-level container for campaigns. It carries brand identity, default optimization mode, default budget type, and (optionally) UTM parameters and frequency caps that flow down to its campaigns.
curl -X POST "https://api.agentic.scope3.com/api/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",
    "campaignBudgetType": "total_budget",
    "sandbox": false
  }'
Key fields:
FieldDescription
nameDisplay name for the advertiser (1–255 chars).
brandDomain (e.g. acme.com) or full manifest URL. Identity is resolved from /.well-known/brand.json or the AdCP brand registry.
optimizationApplyModeAUTO applies Scope3 AI optimizations automatically; MANUAL requires approval. Defaults to MANUAL.
campaignBudgetTypetotal_budget — the campaign budget covers media spend and Scope3 fees.
sandboxWhen true, all downstream ADCP calls run against sandbox-flagged accounts — no real spend. Immutable after creation.
linkedAccountsOptional partner-platform accounts to link at creation (e.g. Snap, Google).
utmConfigDefault UTM parameters appended to landing-page redirects.
frequencyCapsBuyer-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.
4

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.agentic.scope3.com/api/buyer/advertisers/12345/measurement-config" \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mmmEnabled": true,
    "mmmConfig": {
      "provider": "scope3",
      "reportingFrequency": "weekly"
    },
    "incrementalityTestingEnabled": false,
    "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.agentic.scope3.com/api/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.
5

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.agentic.scope3.com/api/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": { "total": 50000, "currency": "USD" },
    "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/buyer/discovery/:id/discover-products again with refine to narrow results, or use POST /api/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.
6

Step 6: Create your first campaign

A campaign references an advertiser and a (preselected) discovery session. The minimum required fields are advertiserId, name, flightDates, budget, and campaignType.
curl -X POST "https://api.agentic.scope3.com/api/buyer/campaigns" \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "advertiserId": "12345",
    "name": "Acme Q2 CTV Launch",
    "campaignType": "DECISIONED",
    "flightDates": {
      "startDate": "2026-05-01T00:00:00Z",
      "endDate": "2026-05-31T23:59:59Z"
    },
    "budget": { "total": 50000, "currency": "USD" },
    "constraints": {
      "channels": ["ctv", "video"],
      "countries": ["US"]
    },
    "discoveryId": "disc_abc123",
    "productIds": ["prod_xyz789"]
  }'
Response:
{
  "data": {
    "campaign": {
      "campaignId": "cmp_67890",
      "advertiserId": "12345",
      "name": "Acme Q2 CTV Launch",
      "status": "DRAFT",
      "campaignType": "DECISIONED"
    }
  }
}
Capture the campaignId from the response — we’ll use this cmp_* id in Steps 7–8.Key choices:
FieldNotes
campaignTypeDECISIONED — Scope3 optimizes media buys. ROUTED — pass-through to the sales agent using your linked credentials. Immutable after creation.
discoveryId + productIdsAttach a discovery session and pre-select products. Optional but typical.
performanceConfigAdd optimization goals tied to event sources or pacing metrics.
pacingPeriodsTime-based pacing schedule with weight or fixed budget per period.
audienceConfigTarget / suppress audience IDs from the signals catalog.
The campaign is created in DRAFT status — nothing has been sent to a sales agent yet.
7

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.agentic.scope3.com/api/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/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.
8

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.agentic.scope3.com/api/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/buyer/campaigns/:id/execute while the campaign is still DRAFT.
execute and reactivate are different endpoints. Use POST /api/buyer/campaigns/:id/execute to launch a DRAFT (or COMPLETED) campaign. To resume a PAUSED campaign, use POST /api/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.agentic.scope3.com/api/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.agentic.scope3.com/api/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.

​
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.