Conversion API (ECAPI)

v1 is deprecated. August 1, 2026 is the final day these endpoints will be available. Migrate to v2, which is the current stable API.

Overview

Scope3’s Conversion API follows the AdCP log_event specification for server-to-server conversion measurement. This enables you to:

Send purchase, sign-up, and other conversion events
Attribute conversions back to ad impressions and clicks
Optimize campaigns based on actual outcomes

Privacy-First Design: This is a “proxy CAPI” - we only accept pre-resolved identity tokens (e.g., LiveRamp RampIDs, ID5 IDs). Raw PII (emails, phone numbers, addresses) is NOT accepted.

Prerequisites

Before sending conversion events, you’ll need two things:

1. Configure an Event Source

Use the sync_event_sources tool to register an event source for your account. This gives you an event_source_id to include in all event requests:

// Call tool: sync_event_sources
{
  "event_sources": [
    {
      "event_source_id": "website_pixel",
      "name": "Website Pixel",
      "event_types": ["purchase", "lead", "add_to_cart"],
      "allowed_domains": ["example.com"]
    }
  ]
}

// Response:
{
  "event_sources": [
    { "event_source_id": "website_pixel", "action": "created" }
  ]
}

The tool uses upsert semantics — action will be created, updated, or unchanged on subsequent calls. Always run this before sending events for the first time.

2. Get Your API Key

Visit agentic.scope3.com/api-keys
Sign up or log into your Scope3 account
Generate a new API key (starts with scope3_)

See Authentication for detailed setup instructions.

Endpoints

Production
Staging

POST https://ping.scope3.com/agentic/v1/capi
Content-Type: application/json
Authorization: Bearer scope3_<your_api_key>

POST https://ping.staging.scope3.com/agentic/v1/capi
Content-Type: application/json
Authorization: Bearer scope3_<your_api_key>

Use the staging endpoint for testing and development. Events sent to staging won’t affect production campaigns.

Request Format

Minimal Example (Purchase with Click ID)

{
  "event_source_id": "website_pixel",
  "events": [
    {
      "event_id": "order_12345",
      "event_type": "purchase",
      "event_time": "2026-01-15T14:30:00Z",
      "action_source": "website",
      "user_match": {
        "click_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "click_id_type": "sc3clid"
      },
      "custom_data": {
        "value": 99.99,
        "currency": "USD"
      }
    }
  ]
}

Full Example (with Identity Tokens)

{
  "event_source_id": "website_pixel",
  "events": [
    {
      "event_id": "order_12345",
      "event_type": "purchase",
      "event_time": "2026-01-15T14:30:00Z",
      "action_source": "website",
      "user_match": {
        "click_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "click_id_type": "sc3clid",
        "uids": [
          { "type": "rampid", "value": "XY1234567890AB" },
          { "type": "id5", "value": "ID5-ABCDEF123456" }
        ]
      },
      "custom_data": {
        "value": 149.99,
        "currency": "USD",
        "order_id": "txn_12345",
        "contents": [{ "id": "SKU-001", "quantity": 3, "price": 49.99 }]
      }
    }
  ]
}

Request Fields

Top-Level

Field	Type	Required	Description
`event_source_id`	string	Yes	Event source ID configured via `sync_event_sources`
`events`	Event[]	Yes	Events to log (min 1, max 10,000)
`test_event_code`	string	No	Validate events without affecting production data (see Test Events)

Event Object

Field	Type	Required	Description
`event_id`	string	Yes	Unique identifier for deduplication. Max 256 chars.
`event_type`	string	Yes	Event type (see supported types below)
`event_time`	string	Yes	ISO 8601 timestamp when the event occurred
`user_match`	object	No	User identification data (see below)
`custom_data`	object	No	Event-specific data (value, currency, items)
`action_source`	string	No	Where the event occurred (`website`, `app`, `in_store`, etc.)
`event_source_url`	string	No	URL where the event occurred

UserMatch Object

Field	Type	Description
`click_id`	string	Click identifier from the landing page URL
`click_id_type`	string	Type of click ID. For Scope3 ads, use `sc3clid`. Also accepts `gclid`, `fbclid`, `ttclid`, etc.
`uids`	UID[]	Pre-resolved universal IDs (see Supported Identity Providers)

CustomData Object

Field	Type	Description
`value`	number	Monetary value of the event
`currency`	string	ISO 4217 currency code (e.g., “USD”, “EUR”)
`order_id`	string	Unique order or transaction identifier
`num_items`	integer	Number of items in the event
`contents`	Content[]	Per-item details: `id`, `quantity`, `price`

Supported Event Types

Commerce Events

| Event Type | Description | |------------|-------------| | purchase | User completes a purchase | | add_to_cart | User adds item to cart | | initiate_checkout | User begins checkout | | add_payment_info | User adds payment info |

Lead Events

| Event Type | Description | |------------|-------------| | lead | Lead generated | | complete_registration | User completes registration | | subscribe | User subscribes |

Engagement Events

| Event Type | Description | |------------|-------------| | page_view | User views a page | | view_content | User views content |

See the AdCP conversion tracking spec for the complete list of supported event types.

Attribution Methods

Scope3 supports two attribution methods depending on your use case:

Method	Use Case	How It Works
Click Attribution	Online conversions (same session/device)	Pass the `sc3clid` from the landing page URL
Offline Attribution	Cross-device or offline conversions	Pass pre-resolved identity tokens (UIDs)

Click Attribution (Online)

When a user clicks an ad served through Scope3, we append a unique sc3clid parameter to the landing page URL:

https://your-site.com/landing?sc3clid=01ARZ3NDEKTSV4RRFFQ69G5FAV&axem=...

To enable click attribution:

Capture the sc3clid from the URL when the user lands
Store it (cookie, session, or database)
Include it as user_match.click_id with click_id_type: "sc3clid" when sending conversion events

{
  "event_source_id": "website_pixel",
  "events": [
    {
      "event_id": "order_12345",
      "event_type": "purchase",
      "event_time": "2026-01-15T14:30:00Z",
      "action_source": "website",
      "user_match": {
        "click_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "click_id_type": "sc3clid"
      },
      "custom_data": {
        "value": 99.99,
        "currency": "USD"
      }
    }
  ]
}

Click attribution is the simplest and most accurate method when the user converts in the same browser session.

Offline Attribution (Cross-Device / Offline)

For conversions that happen on a different device or offline, use pre-resolved identity tokens. These allow Scope3 to match the conversion back to ad exposure even without a click ID. Use cases:

User sees ad on mobile, purchases on desktop
User sees ad online, purchases in physical store
CRM/offline sales data upload

{
  "event_source_id": "crm_import",
  "events": [
    {
      "event_id": "store_txn_20260115_001",
      "event_type": "purchase",
      "event_time": "2026-01-15T16:45:00Z",
      "action_source": "in_store",
      "user_match": {
        "uids": [
          { "type": "rampid", "value": "XY1234567890AB" },
          { "type": "id5", "value": "ID5-ABCDEF123456" }
        ]
      },
      "custom_data": {
        "value": 149.99,
        "currency": "USD"
      }
    }
  ]
}

Supported Identity Providers

Type	Description
`rampid`	LiveRamp RampID (person-based)
`id5`	ID5 ID (device-based)

Identity tokens must be resolved upstream via your identity partner. We do NOT accept raw PII (emails, phone numbers, addresses) for resolution.

Test Events

Use test_event_code to validate your integration without affecting production attribution or reporting:

{
  "event_source_id": "website_pixel",
  "test_event_code": "TEST_12345",
  "events": [
    {
      "event_id": "test_evt_001",
      "event_type": "purchase",
      "event_time": "2026-01-15T14:30:00Z",
      "action_source": "website",
      "user_match": {
        "click_id": "test_click_abc",
        "click_id_type": "sc3clid"
      },
      "custom_data": {
        "value": 99.99,
        "currency": "USD"
      }
    }
  ]
}

Test events appear in the test events UI but do not affect production campaigns.

Response Format

Success (200 OK)

{
  "status": "success"
}

Error Responses

Status	Error	Description
400	Invalid JSON payload	Malformed JSON
400	Validation error	Missing required fields
401	Unauthorized	Invalid or missing API key
403	Access denied	API key doesn’t have access to this event source
415	Content-Type must be application/json	Wrong content type

Code Examples

cURL
Python
JavaScript

curl -X POST https://ping.scope3.com/agentic/v1/capi \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer scope3_<your_api_key>" \
  -d '{
    "event_source_id": "website_pixel",
    "events": [
      {
        "event_id": "order_12345",
        "event_type": "purchase",
        "event_time": "2026-01-15T14:30:00Z",
        "action_source": "website",
        "user_match": {
          "click_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
          "click_id_type": "sc3clid"
        },
        "custom_data": {
          "value": 99.99,
          "currency": "USD"
        }
      }
    ]
  }'

import requests
from datetime import datetime, timezone

response = requests.post(
    "https://ping.scope3.com/agentic/v1/capi",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer scope3_<your_api_key>"
    },
    json={
        "event_source_id": "website_pixel",
        "events": [
            {
                "event_id": "order_12345",
                "event_type": "purchase",
                "event_time": datetime.now(timezone.utc).isoformat(),
                "action_source": "website",
                "user_match": {
                    "click_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                    "click_id_type": "sc3clid"
                },
                "custom_data": {
                    "value": 99.99,
                    "currency": "USD"
                }
            }
        ]
    }
)
print(response.json())

const response = await fetch('https://ping.scope3.com/agentic/v1/capi', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer scope3_<your_api_key>'
  },
  body: JSON.stringify({
    event_source_id: 'website_pixel',
    events: [
      {
        event_id: 'order_12345',
        event_type: 'purchase',
        event_time: new Date().toISOString(),
        action_source: 'website',
        user_match: {
          click_id: '01ARZ3NDEKTSV4RRFFQ69G5FAV',
          click_id_type: 'sc3clid'
        },
        custom_data: {
          value: 99.99,
          currency: 'USD'
        }
      }
    ]
  })
});

const result = await response.json();
console.log(result);

Best Practices

Always Capture Click ID

Store the sc3clid parameter immediately when users land from ads. Use cookies, session storage, or your database to persist it until conversion.

Send Events Server-Side

Never expose your API key in client-side code. Always send conversion events from your backend server.

Include Transaction ID

Include a unique event_id field for each event to help with deduplication. This prevents duplicate conversions from being counted.

Use Accurate Timestamps

Send the actual event time as an ISO 8601 string, not the time you’re sending the request. This ensures accurate attribution windows.

Test in Staging First

Use the staging endpoint (ping.staging.scope3.com) to validate your integration before sending events to production.

Next Steps

Outcomes Agents

Configure optimization agents to use your conversion data

Campaign Setup

Set up campaigns to optimize for conversions

Reporting

Analyze conversion performance across campaigns

Authentication

Learn more about API key management

Overview

Features

Object Guides

Optimization

Integrations

Reporting & Analytics

Release Notes

Overview

Prerequisites

1. Configure an Event Source

2. Get Your API Key

Endpoints

Request Format

Minimal Example (Purchase with Click ID)

Full Example (with Identity Tokens)

Request Fields

Top-Level

Event Object

UserMatch Object

CustomData Object

Supported Event Types

Attribution Methods

Click Attribution (Online)

Offline Attribution (Cross-Device / Offline)

Supported Identity Providers

Test Events

Response Format

Success (200 OK)

Error Responses

Code Examples

Best Practices

Next Steps

Outcomes Agents

Campaign Setup

Reporting

Authentication

Overview

Features

Object Guides

Optimization

Integrations

Reporting & Analytics

Release Notes

Documentation Index

​Overview

​Prerequisites

​1. Configure an Event Source

​2. Get Your API Key

​Endpoints

​Request Format

​Minimal Example (Purchase with Click ID)

​Full Example (with Identity Tokens)

​Request Fields

​Top-Level

​Event Object

​UserMatch Object

​CustomData Object

​Supported Event Types

​Attribution Methods

​Click Attribution (Online)

​Offline Attribution (Cross-Device / Offline)

​Supported Identity Providers

​Test Events

​Response Format

​Success (200 OK)

​Error Responses

​Code Examples

​Best Practices

​Next Steps

Outcomes Agents

Campaign Setup

Reporting

Authentication

Overview

Prerequisites

1. Configure an Event Source

2. Get Your API Key

Endpoints

Request Format

Minimal Example (Purchase with Click ID)

Full Example (with Identity Tokens)

Request Fields

Top-Level

Event Object

UserMatch Object

CustomData Object

Supported Event Types

Attribution Methods

Click Attribution (Online)

Offline Attribution (Cross-Device / Offline)

Supported Identity Providers

Test Events

Response Format

Success (200 OK)

Error Responses

Code Examples

Best Practices

Next Steps