Skip to main content

​
Overview

Sandbox mode lets you exercise the full Scope3 media buying workflow — advertiser creation, account registration, campaign execution — without triggering real platform operations or real spend. All ADCP calls for a sandbox advertiser route through the ADCP sandbox environment automatically.

Safe Integration Testing

Validate your agent workflows end-to-end before going live. No real bids, no real spend.

Full Workflow Coverage

Sandbox follows the same code paths as production — advertiser, account registration, and media buy execution.

​
How It Works

When a sandbox advertiser executes a media buy, the API automatically:
  1. Detects the advertiser is sandboxed via the seat_sandbox record
  2. Verifies the sales agent declares sandbox support in get_adcp_capabilities
  3. Looks up the registered sandbox account for the sales agent
  4. Injects the sandbox account_id into the ADCP create_media_buy request
The same account scoping applies to delivery queries. When fetching or listing media buys, the API resolves the correct account reference (sandbox or production) and includes it in every get_media_buy_delivery call. This ensures delivery data is fetched from the correct environment and prevents sandbox results from appearing alongside production data.

​
Creating a Sandbox Advertiser

​
Via API

Set sandbox: true in the create advertiser request body: 
curl -X POST "https://api.agentic.scope3.com/api/v2/buyer/advertisers" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp (Sandbox)",
    "description": "Integration testing advertiser",
    "sandbox": true
  }'
Response: 
{
  "data": {
    "id": "adv_abc123",
    "name": "Acme Corp (Sandbox)",
    "description": "Integration testing advertiser",
    "status": "active",
    "sandbox": true,
    "createdAt": "2026-02-22T21:35:44Z",
    "updatedAt": "2026-02-22T21:35:44Z",
    "linkedBrand": null,
    "brand": null,
    "brandWarning": null
  }
}

​
Via UI

When creating an advertiser in the dashboard, toggle the Sandbox switch before saving. Sandbox advertisers are shown with a badge in the advertiser list for easy identification.
Sandbox is permanent. Once an advertiser is created with sandbox: true, the flag cannot be changed. This protects against accidentally switching an advertiser from sandbox to production after accounts and campaigns have been configured.

​
Registering a Sandbox Account

Before executing media buys, a sandbox credential must be registered for the sales agent. Use the standard account registration endpoint, passing the sandbox advertiser’s ID as advertiserId. The API reads the advertiser’s sandbox flag and marks the credential as sandbox automatically. 
# Register a partner agent account for the sandbox advertiser
curl -X POST "https://api.agentic.scope3.com/api/v2/partner/agents/{agentId}/accounts" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "advertiserId": "12345",
    "accountIdentifier": "my-sandbox-account",
    "auth": { "type": "api_key", "token": "your-sandbox-api-key" }
  }'
FieldRequiredDescription
advertiserIdYesThe numeric advertiser seat ID. The API validates ownership and reads the sandbox flag.
accountIdentifierYesThe account identifier recognized by the sales agent.
authDependsAuth credentials. Required for API_KEY/JWT agents; omit for OAUTH (redirect flow).
Once accounts are discovered via list_accounts, they are stored in adcp_agent_accounts with sandbox = true and used automatically during media buy execution. Sandbox accounts are strictly isolated — a sandbox advertiser can only link sandbox accounts, and a production advertiser can only link production accounts.
The sales agent must declare sandbox support in get_adcp_capabilities (via the extensions array or _raw.sandbox field). Media buy execution will fail if the agent does not support sandbox mode.

​
Executing Media Buys in Sandbox

Once a sandbox account is registered, media buy execution is identical to production — the API handles sandbox routing transparently: 
curl -X POST "https://api.agentic.scope3.com/api/v2/buyer/media-buys/execute" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaBuyId": "mb_def456"
  }'
Behind the scenes, the API:
  1. Reads the seat_id from the media buy record
  2. Checks seat_sandbox — detects sandbox: true
  3. Calls get_adcp_capabilities on the sales agent (cached 24 h) — verifies the agent declares sandbox support via the extensions array or _raw.sandbox field
  4. Queries adcp_agent_accounts (joined through adcp_agent_credentials) for an active sandbox account for the sales agent
  5. Injects account_id into the ADCP create_media_buy request
Execution fails explicitly for misconfigurations — there is no silent fallback to production. Two errors are possible:Agent does not support sandbox:
Cannot execute media buy for sandbox advertiser: sales agent <id> does not declare
sandbox support in get_adcp_capabilities. Use a sandbox-capable sales agent or
contact the publisher.
No sandbox account registered:
Cannot execute media buy for sandbox advertiser: no sandbox account registered
for sales agent <id>. Register a sandbox account first.

​
Identifying and Filtering Sandbox Advertisers

The sandbox field is returned on every advertiser response. Use the optional sandbox query parameter to filter the list: 
# List only sandbox advertisers
curl "https://api.agentic.scope3.com/api/v2/buyer/advertisers?sandbox=true" \
  -H "Authorization: Bearer your-api-key"

# List only production advertisers
curl "https://api.agentic.scope3.com/api/v2/buyer/advertisers?sandbox=false" \
  -H "Authorization: Bearer your-api-key"

# List all advertisers (omit the parameter entirely)
curl "https://api.agentic.scope3.com/api/v2/buyer/advertisers" \
  -H "Authorization: Bearer your-api-key"

{
  "data": [
    { "id": "adv_abc123", "name": "Acme Corp (Sandbox)", "sandbox": true, ... },
    { "id": "adv_def456", "name": "Beta Brand",          "sandbox": false, ... }
  ]
}
In the dashboard, sandbox advertisers are shown with a Sandbox badge in the advertiser list so they are easy to distinguish from production advertisers at a glance.

​
Product Discovery in Sandbox

Product discovery (GET /bundles/discover-products) also respects sandbox status. When a sandbox advertiser is passed as advertiserId, the API:
  1. Calls sync_accounts (for implicit_from_sync agents) with the sandbox credential to ensure the seller has provisioned an account for that advertiser
  2. Looks up the registered sandbox account_id for each eligible sales agent
  3. Injects that account_id into the get_products ADCP call
Agents that do not declare sandbox support in get_adcp_capabilities are automatically excluded from product discovery results for sandbox advertisers. This ensures only sandbox-capable agents surface products during integration testing.

​
Key Constraints

ConstraintDetail
Immutable flagsandbox cannot be changed after creation
Agent capability requiredThe sales agent must declare sandbox support in get_adcp_capabilities
Sandbox account requiredMedia buy execution fails explicitly if no sandbox account is discovered
Strict account isolationSandbox accounts are tracked via sandbox = true in adcp_agent_accounts. A sandbox advertiser can only list and link sandbox accounts; a production advertiser can only list and link production accounts.
Delivery scoped to accountget_media_buy_delivery always includes the resolved account reference — sandbox advertisers get their sandbox account_id, production advertisers get their production account.
Full workflow requiredYou must register a credential and have accounts discovered before executing media buys

​
Next Steps

Advertiser API Reference

Full schema for POST /advertisers, including the sandbox field.

Built for Agents

Connect AI agents via MCP to manage sandbox advertisers conversationally.