sync_event_sources

sync_event_sources task — configure website pixels, mobile SDKs, server-to-server integrations, and seller- or platform-native event sources on AdCP seller accounts for conversion tracking and attribution.

Configure event sources on a seller account for conversion tracking. Sources can be buyer-managed integrations such as website pixels, mobile SDKs, server-to-server feeds, and CRM imports, or seller- and platform-native owned properties such as channels, profiles, feeds, podcasts, and newsletter lists. Supports upsert semantics, seller-managed sources, and setup instructions.

Response Time: ~1s (synchronous configuration)

Request Schema: /schemas/v3/media-buy/sync-event-sources-request.json Response Schema: /schemas/v3/media-buy/sync-event-sources-response.json

Quick Start

Configure an event source for purchase tracking:

JavaScript

import { testAgent } from "@adcp/sdk/testing";
import { SyncEventSourcesResponseSchema } from "@adcp/sdk";

const result = await testAgent.syncEventSources({
  account: { account_id: "acct_12345" },
  event_sources: [
    {
      event_source_id: "website_pixel",
      name: "Main Website Pixel",
      event_types: ["purchase", "lead", "add_to_cart"],
      allowed_domains: ["www.example.com", "shop.example.com"],
    },
  ],
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

// Validate response against schema
const validated = SyncEventSourcesResponseSchema.parse(result.data);

// Check for operation-level errors first (discriminated union)
if ("errors" in validated && validated.errors) {
  throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}

if ("event_sources" in validated) {
  for (const source of validated.event_sources) {
    console.log(`${source.event_source_id}: ${source.action}`);
    if (source.setup?.snippet) {
      console.log(`  Install: ${source.setup.snippet_type}`);
    }
  }
}

import asyncio
from adcp.testing import test_agent

async def main():
    result = await test_agent.simple.sync_event_sources(
        account={'account_id': 'acct_12345'},
        event_sources=[{
            'event_source_id': 'website_pixel',
            'name': 'Main Website Pixel',
            'event_types': ['purchase', 'lead', 'add_to_cart'],
            'allowed_domains': ['www.example.com', 'shop.example.com']
        }]
    )

    # Check for operation-level errors first
    if hasattr(result, 'errors') and result.errors:
        raise Exception(f"Operation failed: {result.errors}")

    for source in result.event_sources:
        print(f"{source.event_source_id}: {source.action}")
        if source.setup and source.setup.snippet:
            print(f"  Install: {source.setup.snippet_type}")

asyncio.run(main())

Request Parameters

Parameter	Type	Required	Description
account	account-ref	Yes	Account reference. Pass { "account_id": "..." } or { "brand": {...}, "operator": "..." } if the seller supports implicit resolution.
event_sources	EventSource[]	No	Event sources to sync. When omitted, the call is discovery-only and returns all existing event sources without modification.
delete_missing	boolean	No	When true, buyer-managed event sources on the account not in this request are removed (default: false)

Event Source Object

Field	Type	Required	Description
event_source_id	string	Yes	Unique identifier for this event source
name	string	No	Human-readable name
event_types	EventType[]	No	Event types this source handles. If omitted, accepts all event types.
action_source	ActionSource	No	Flat source category for compatibility (website, app, system_generated, etc.). Pair with surface when the flat value is too coarse.
allowed_domains	string[]	No	Domains authorized to send events for this source
surface	EventSurface	No	Structured surface this source represents, such as an owned channel, profile, feed, podcast, newsletter list, website, app, or store

Response

Success Response:

• event_sources - Results for each event source, including both synced and seller-managed sources on the account

Error Response:

• errors - Array of operation-level errors (auth failure, account not found)

Note: Responses use discriminated unions - you get either success fields OR errors, never both.

Each event source in success response includes:

• All request fields
• seller_id - Seller-assigned identifier for this event source
• action - What happened: created, updated, unchanged, deleted, failed
• action_source - Type of event source (website pixel, app SDK, etc.)
• surface - Structured surface this source represents, when the flat action_source is too coarse
• managed_by - Who manages this source: buyer or seller
• setup - Implementation details (snippet, instructions)
• health - Event source health assessment (when seller supports health scoring)
• errors - Per-source errors (only when action: "failed")
• ext - Per-source extension metadata, such as platform-native conversion IDs, attribution-window handles, or raw origin strings

See schema for complete field list: sync-event-sources-response.json

Event Source Health

Sellers that evaluate event source quality include a health object on each source in the response. This is analogous to Snap’s Event Quality Score or Meta’s Event Match Quality — it tells the buyer whether their event integration is working well enough for optimization.

Field	Type	Description
status	string	AdCP-standardized health level: insufficient, minimum, good, excellent. Use this for cross-seller decisions.
detail	object	Seller-specific scoring (optional). Contains score, max_score, and optional label. Only present when the seller has a native quality score.
match_rate	number	Fraction of events matched to ad interactions (0.0-1.0).
last_event_at	date-time	Timestamp of the most recent event received.
evaluated_at	date-time	When this health assessment was computed. Stale for sellers computing from reporting data.
events_received_24h	integer	Events received in the last 24 hours (0 = not firing).
issues	array	Actionable problems with severity (error, warning, info) and message. Sort by severity — don’t rely on array position.

test=false

{
  "event_sources": [
    {
      "event_source_id": "web_pixel",
      "action": "unchanged",
      "managed_by": "buyer",
      "health": {
        "status": "good",
        "detail": { "score": 7.2, "max_score": 10, "label": "Event Match Quality" },
        "match_rate": 0.72,
        "last_event_at": "2026-03-23T14:22:00Z",
        "evaluated_at": "2026-03-23T14:30:00Z",
        "events_received_24h": 14200,
        "issues": [
          {
            "severity": "warning",
            "message": "Missing hashed_email parameter on 38% of purchase events. Adding this improves match rate for cross-device attribution."
          }
        ]
      }
    }
  ]
}

Buyer agents should key decisions off status, not detail.score. The four-tier status is comparable across all sellers — a buyer agent writes one rule (“require good or better for DR products”) that works everywhere. The detail object is for human dashboards or advanced diagnostics.

Buyer agents can use health data to:

• Gate product selection on event quality (e.g., require good or better for DR products)
• Surface setup issues to the buyer before campaign launch
• Prioritize which event sources to fix first

Common Scenarios

Discovery Only

Discover all event sources on an account (including seller-managed sources) without making changes. Useful for platform-managed conversion tracking where the seller provides always-on attribution:

JavaScript

import { testAgent } from "@adcp/sdk/testing";
import { SyncEventSourcesResponseSchema } from "@adcp/sdk";

const result = await testAgent.syncEventSources({
  account: { account_id: "acct_12345" },
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = SyncEventSourcesResponseSchema.parse(result.data);

if ("errors" in validated && validated.errors) {
  throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}

if ("event_sources" in validated) {
  for (const source of validated.event_sources) {
    console.log(`${source.event_source_id} (${source.managed_by}): ${source.name}`);
  }
}

import asyncio
from adcp.testing import test_agent

async def main():
    result = await test_agent.simple.sync_event_sources(
        account={'account_id': 'acct_12345'}
    )

    if hasattr(result, 'errors') and result.errors:
        raise Exception(f"Operation failed: {result.errors}")

    for source in result.event_sources:
        print(f"{source.event_source_id} ({source.managed_by}): {source.name}")

asyncio.run(main())

Multiple Event Sources

Configure separate sources for website and app:

JavaScript

import { testAgent } from "@adcp/sdk/testing";
import { SyncEventSourcesResponseSchema } from "@adcp/sdk";

const result = await testAgent.syncEventSources({
  account: { account_id: "acct_12345" },
  event_sources: [
    {
      event_source_id: "web_pixel",
      name: "Website Pixel",
      event_types: ["purchase", "lead", "add_to_cart", "view_content"],
      allowed_domains: ["www.example.com"],
    },
    {
      event_source_id: "app_sdk",
      name: "Mobile App SDK",
      event_types: ["purchase", "app_install", "app_launch"],
    },
  ],
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = SyncEventSourcesResponseSchema.parse(result.data);

if ("errors" in validated && validated.errors) {
  throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}

if ("event_sources" in validated) {
  for (const source of validated.event_sources) {
    console.log(`${source.event_source_id} (${source.managed_by}): ${source.action}`);
  }
}

import asyncio
from adcp.testing import test_agent

async def main():
    result = await test_agent.simple.sync_event_sources(
        account={'account_id': 'acct_12345'},
        event_sources=[
            {
                'event_source_id': 'web_pixel',
                'name': 'Website Pixel',
                'event_types': ['purchase', 'lead', 'add_to_cart', 'view_content'],
                'allowed_domains': ['www.example.com']
            },
            {
                'event_source_id': 'app_sdk',
                'name': 'Mobile App SDK',
                'event_types': ['purchase', 'app_install', 'app_launch']
            }
        ]
    )

    if hasattr(result, 'errors') and result.errors:
        raise Exception(f"Operation failed: {result.errors}")

    for source in result.event_sources:
        print(f"{source.event_source_id} ({source.managed_by}): {source.action}")

asyncio.run(main())

Discovering Seller-Managed Sources

Sellers may provide always-on event sources (e.g. Amazon sales attribution). These appear in the response with managed_by: "seller" alongside your buyer-managed sources:

test=false

{
  "event_sources": [
    {
      "event_source_id": "web_pixel",
      "name": "Website Pixel",
      "seller_id": "px_abc123",
      "action": "created",
      "managed_by": "buyer",
      "setup": {
        "snippet": "<script src=\"https://seller.example/pixel/px_abc123.js\"></script>",
        "snippet_type": "javascript",
        "instructions": "Place this tag in the <head> of all pages where you want to track events."
      }
    },
    {
      "event_source_id": "seller_sales_attribution",
      "name": "Sales Attribution",
      "seller_id": "internal_attr",
      "action": "unchanged",
      "managed_by": "seller",
      "action_source": "in_store"
    }
  ]
}

Products with conversion_tracking.platform_managed: true indicate the seller provides these sources.

Creator and Owned-Property Sources

Seller-managed creator or owned-property sources use the same event_sources array, with a flat action_source for compatibility and surface for structured context:

test=false

{
  "event_sources": [
    {
      "event_source_id": "creator_channel",
      "name": "Creator Channel Events",
      "seller_id": "creator_attr_001",
      "event_types": ["follow", "content_view", "watch_milestone"],
      "action_source": "system_generated",
      "surface": {
        "category": "owned_property",
        "property_type": "channel",
        "namespace": "video_platform",
        "property_id": "channel_123"
      },
      "managed_by": "seller",
      "action": "unchanged",
      "ext": {
        "video_platform": {
          "native_origin": "owned_channel"
        }
      }
    }
  ]
}

Use follow for free durable opt-ins to a channel, profile, feed, list, or podcast. Use subscribe only for paid subscriptions or paid memberships.

Clean Sync with delete_missing

Replace all buyer-managed event sources on the account:

JavaScript

import { testAgent } from "@adcp/sdk/testing";
import { SyncEventSourcesResponseSchema } from "@adcp/sdk";

const result = await testAgent.syncEventSources({
  account: { account_id: "acct_12345" },
  delete_missing: true,
  event_sources: [
    {
      event_source_id: "unified_pixel",
      name: "Unified Tracking Pixel",
    },
  ],
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = SyncEventSourcesResponseSchema.parse(result.data);

if ("errors" in validated && validated.errors) {
  throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}

if ("event_sources" in validated) {
  for (const source of validated.event_sources) {
    if (source.action === "deleted") {
      console.log(`Removed: ${source.event_source_id}`);
    } else {
      console.log(`Active: ${source.event_source_id} (${source.action})`);
    }
  }
}

import asyncio
from adcp.testing import test_agent

async def main():
    result = await test_agent.simple.sync_event_sources(
        account={'account_id': 'acct_12345'},
        delete_missing=True,
        event_sources=[{
            'event_source_id': 'unified_pixel',
            'name': 'Unified Tracking Pixel'
        }]
    )

    if hasattr(result, 'errors') and result.errors:
        raise Exception(f"Operation failed: {result.errors}")

    for source in result.event_sources:
        if source.action == 'deleted':
            print(f"Removed: {source.event_source_id}")
        else:
            print(f"Active: {source.event_source_id} ({source.action})")

asyncio.run(main())

Setup Instructions

The response includes setup details for each event source. The setup object tells you how to activate the source:

snippet_type	Description	Action Required
javascript	JavaScript tag for website pages	Place in <head> of tracked pages
html	HTML pixel/iframe	Place before </body>
pixel_url	URL that fires on events	Send GET request on each event
server_only	No client-side tag needed	Use log_event API directly

Error Handling

Error Code	Description	Resolution
ACCOUNT_NOT_FOUND	Account does not exist	Verify account_id from account setup
INVALID_EVENT_TYPE	Unrecognized event type	Check seller’s supported_event_types in get_adcp_capabilities
DUPLICATE_EVENT_SOURCE_ID	Multiple sources with same ID in request	Use unique event_source_id values
RATE_LIMITED	Too many sync requests	Wait and retry with exponential backoff

Best Practices

1. Sync before logging - Always configure event sources before sending events via log_event. Events sent to unconfigured sources will be rejected.

2. Use descriptive IDs - Choose event_source_id values that are meaningful (e.g. web_pixel, app_sdk, crm_import) rather than opaque identifiers.

3. Specify event_types - Restrict each source to relevant event types for better validation and debugging.

4. Check seller capabilities - Use get_adcp_capabilities to discover supported event types, UID types, and action sources before configuring event sources.

5. Install setup snippets - When the response includes setup instructions, install the provided snippet before logging events. Server-only sources (snippet_type: "server_only") skip this step.

6. Handle seller-managed sources - The response may include sources with managed_by: "seller" that you didn’t configure. These are always-on and provide additional attribution data.

Next Steps

• Conversion Tracking - Data model, optimization goals, and the end-to-end flow
• log_event - Send marketing events to configured event sources
• create_media_buy - Set optimization goals on packages referencing event sources
• get_media_buy_delivery - Monitor conversion metrics in delivery reports