Conversion API (ECAPI)

Overview

Scope3’s Conversion API follows the IAB Tech Lab ECAPI v1.0 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. Get Your Dataset ID

Use the customer_dataset_get_id MCP tool to retrieve your dataset ID:

// Call tool: customer_dataset_get_id
// No parameters required

// Response:
{
  "datasetId": "ds_abc123xyz",
  "customerId": 12345
}

Each customer has one dataset ID used for grouping conversion data. The tool will create a new dataset if none exists.

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/events
Content-Type: application/json
Authorization: Bearer scope3_<your_api_key>

POST https://ping.staging.scope3.com/agentic/v1/events
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)

{
  "data_set_id": "ds_abc123xyz",
  "event_type": "purchase",
  "timestamp": 1706500000,
  "value": 99.99,
  "currency": "USD",
  "user_data": {
    "click_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
  }
}

Full Example (with Identity Tokens)

{
  "data_set_id": "ds_abc123xyz",
  "event_type": "purchase",
  "timestamp": 1706500000,
  "id": "order_12345",
  "source": "website",
  "value": 149.99,
  "currency": "USD",
  "user_data": {
    "click_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "external_id": "user_abc123",
    "uids": [
      {
        "id": "XY1234567890AB",
        "source": "liveramp.com",
        "atype": 3
      },
      {
        "id": "ID5-ABCDEF123456",
        "source": "id5-sync.com",
        "atype": 1
      }
    ]
  },
  "properties": {
    "transaction_id": "txn_12345",
    "items": [
      {
        "id": "SKU-001",
        "name": "Product Name",
        "price": 49.99,
        "quantity": 3
      }
    ]
  }
}

Required Fields

Field	Type	Description
`data_set_id`	string	Your dataset ID (from `customer_dataset_get_id` tool)
`event_type`	string	Event type (see supported types below)
`timestamp`	integer	Unix epoch timestamp in seconds

Optional Fields

Field	Type	Description
`id`	string	Unique event identifier (for deduplication)
`source`	string	Event source (e.g., “website”, “app”, “pos”)
`value`	number	Monetary value of the conversion
`currency`	string	ISO 4217 currency code (e.g., “USD”, “EUR”)
`user_data`	object	User identification data (see below)
`properties`	object	Additional event properties

Supported Event Types

Commerce Events

Event Type	Description
`purchase`	User completes a purchase
`add_to_cart`	User adds item to cart
`begin_checkout`	User begins checkout
`add_payment_info`	User adds payment info

Lead Events

Event Type	Description
`lead`	Lead generated
`sign_up`	User signs up
`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 IAB ECAPI 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 `clkid` 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 clkid parameter to the landing page URL:

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

To enable click attribution:

Capture the clkid from the URL when the user lands
Store it (cookie, session, or database)
Include it as user_data.click_id when sending conversion events

{
  "data_set_id": "ds_abc123xyz",
  "event_type": "purchase",
  "timestamp": 1706500000,
  "value": 99.99,
  "currency": "USD",
  "user_data": {
    "click_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
  }
}

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

{
  "data_set_id": "ds_abc123xyz",
  "event_type": "purchase",
  "timestamp": 1706500000,
  "value": 149.99,
  "currency": "USD",
  "user_data": {
    "external_id": "user_abc123",
    "uids": [
      {
        "id": "XY1234567890AB",
        "source": "liveramp.com",
        "atype": 3
      },
      {
        "id": "ID5-ABCDEF123456",
        "source": "id5-sync.com",
        "atype": 1
      }
    ]
  }
}

Supported Identity Providers

Provider	Source	atype	Description
LiveRamp	`liveramp.com`	3	RampID (person-based)
ID5	`id5-sync.com`	1	ID5 ID (device-based)

atype values:

atype	Meaning
1	Device ID
3	Person ID

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

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 to dataset	API key doesn’t have access to this dataset
415	Content-Type must be application/json	Wrong content type

Code Examples

cURL
Python
JavaScript

curl -X POST https://ping.scope3.com/agentic/v1/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer scope3_<your_api_key>" \
  -d '{
    "data_set_id": "ds_abc123xyz",
    "event_type": "purchase",
    "timestamp": 1706500000,
    "value": 99.99,
    "currency": "USD",
    "user_data": {
      "click_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
    }
  }'

import requests
import time

response = requests.post(
    "https://ping.scope3.com/agentic/v1/events",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer scope3_<your_api_key>"
    },
    json={
        "data_set_id": "ds_abc123xyz",
        "event_type": "purchase",
        "timestamp": int(time.time()),
        "value": 99.99,
        "currency": "USD",
        "user_data": {
            "click_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
        }
    }
)
print(response.json())

const response = await fetch('https://ping.scope3.com/agentic/v1/events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer scope3_<your_api_key>'
  },
  body: JSON.stringify({
    data_set_id: 'ds_abc123xyz',
    event_type: 'purchase',
    timestamp: Math.floor(Date.now() / 1000),
    value: 99.99,
    currency: 'USD',
    user_data: {
      click_id: '01ARZ3NDEKTSV4RRFFQ69G5FAV'
    }
  })
});

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

Best Practices

Always Capture Click ID

Store the clkid 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 id field for each event to help with deduplication. This prevents duplicate conversions from being counted.

Use Accurate Timestamps

Send the actual event time, 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

Overview

Prerequisites

1. Get Your Dataset ID

2. Get Your API Key

Endpoints

Request Format

Minimal Example (Purchase with Click ID)

Full Example (with Identity Tokens)

Required Fields

Optional Fields

Supported Event Types

Attribution Methods

Click Attribution (Online)

Offline Attribution (Cross-Device / Offline)

Supported Identity Providers

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

​Overview

​Prerequisites

​1. Get Your Dataset ID

​2. Get Your API Key

​Endpoints

​Request Format

​Minimal Example (Purchase with Click ID)

​Full Example (with Identity Tokens)

​Required Fields

​Optional Fields

​Supported Event Types

​Attribution Methods

​Click Attribution (Online)

​Offline Attribution (Cross-Device / Offline)

​Supported Identity Providers

​Response Format

​Success (200 OK)

​Error Responses

​Code Examples

​Best Practices

​Next Steps

Outcomes Agents

Campaign Setup

Reporting

Authentication

Overview

Prerequisites

1. Get Your Dataset ID

2. Get Your API Key

Endpoints

Request Format

Minimal Example (Purchase with Click ID)

Full Example (with Identity Tokens)

Required Fields

Optional Fields

Supported Event Types

Attribution Methods

Click Attribution (Online)

Offline Attribution (Cross-Device / Offline)

Supported Identity Providers

Response Format

Success (200 OK)

Error Responses

Code Examples

Best Practices

Next Steps