Custom Signals - Scope3 Campaign API

Overview

The Scope3 Custom Signals Platform provides real-time resolution of identity and signals for inbound requests. This unified platform hosts custom signals across many identifiers, with audience segments being one type of custom signal alongside geographic, property, and other signal types.

Custom signals enable you to use your first-party data (CRM segments, loyalty tiers, purchase behavior) alongside third-party signals for more precise campaign targeting.

Key Features

Unified Signal Management: Single API for all signal types (audience, geographic, property, custom)
Multi-Identifier Support: Works with MAIDs, RampIDs, postal codes, domains, and more
Real-time API: Fast key-value lookups with sub-millisecond response times
Flexible Data Ingestion: Support for cloud bucket uploads, real-time API updates, and third-party integrations
Auto-expiration: Keys automatically expire after 30 days of inactivity

Custom Signal Types

Custom signals are any data points that can be associated with identifiers to inform advertising decisions:

Audience Segments

CRM-Based Segments

loyalty_tier_gold, loyalty_tier_platinum
high_value_customer, at_risk_churn
recent_purchaser, frequent_buyer

Behavioral Segments

sports_fan, auto_intender, luxury_shopper
bargain_hunter, early_adopter, brand_loyal

Geographic Signals

Location-Based Targeting

high_income_zip, urban_area, ski_region
store_catchment_area, service_territory
competitor_market, expansion_target

Property Signals

Content & Placement

premium_publisher, video_enabled, mobile_app
brand_safe_domain, high_engagement_site
contextually_relevant, category_automotive

Getting Started

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API Key Requirements:

Contact api-support@scope3.com to obtain your API key
Use HTTPS only - API keys should never be sent over HTTP
Store keys securely and rotate them regularly

Quick Start Example

Option 1: Using MCP Tools (Recommended) First, define your signal structure with the MCP tools:

// Define the signal structure
await createCustomSignal({
  name: "Mobile Sports Fans",
  key: "maid",
  description: "Sports fans identified via mobile advertising IDs",
  clusters: [
    {"region": "americas"},
    {"region": "eu"}
  ]
});

Then upload signal data via the data API (see Data Ingestion Methods below). Option 2: Direct API Upload Store audience segments for a mobile advertising ID (MAID):

curl -X POST https://api.scope3.com/signals/maid \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: text/plain" \
  -d "SET abcd-2832-abcd-238-abcd sports_fan auto_intender
ADD aefa-9281-aefa-821-aefa luxury_shopper
DEL aaab-2712-aaab-132-aaab"

Core Concepts

Signal Keys

Signal keys follow the format {identifier_type}:{identifier_value}. Examples:

maid:abcd-2832-abcd-238-abcd (Mobile Advertising ID)
postal_code:90210 (ZIP Code)
domain:cnn.com (Website Domain)

Data Architecture

Auto-Expiration

All keys have a 30-day default TTL that refreshes when accessed, optimizing memory usage.

Scalable Storage

Distributed architecture supports billions of identifiers with sub-millisecond lookup times.

Secure Access

API key authentication ensures your data remains private and secure.

API Reference

Response Formats

All API responses use JSON format with consistent structures:

POST/PUT/DELETE Operations

{
  "status": "success|error",
  "processed": 4,
  "errors": 0,
  "message": "Optional description"
}

Store/Update Signals

curl -X POST https://api.scope3.com/signals/maid \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: text/plain" \
  -d "SET d82a-1811-d82a-921-d82a sports_fan auto_intender
ADD abcd-2832-abcd-238-abcd luxury_shopper
REM aefa-9281-aefa-821-aefa outdated_segment
DEL aaab-2712-aaab-132-aaab"

POST /signals/{key_type} Parameters:

key_type (string): Type of identifier (maid, rampid, postal_code, domain, etc.)

Request Body Operations:

SET - Replace all signals for an identifier
ADD - Add signals to an identifier
REM - Remove specific signals from an identifier
DEL - Remove all signals for an identifier

Retrieve Signals

GET /signals/{key_type}/{identifier}

curl https://api.scope3.com/signals/maid/d82a-1811-d82a-921-d82a \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "identifier": "d82a-1811-d82a-921-d82a",
  "ttl": 18321,
  "signals": ["sports_fan", "auto_intender"]
}

Multi-Field Signals

Store signals for composite keys with multiple fields: POST /signals/{composite_key_types}

curl -X POST https://api.scope3.com/signals/postal_code,domain \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: text/plain" \
  -d "SET sw12,dailymail.co.uk affluent_london news_reader
ADD wc3,telegraph.co.uk premium_content political_interest"

Supported Key Types

Identity Keys

Key Type	Description	Example	Priority
`rampid`	LiveRamp Identity	`RMP_12345`	High
`maid`	Mobile Advertising ID	`abcd-1234-efgh-5678`	High
`id5`	ID5 Universal ID	`ID5_abc123`	Medium
`coreid`	Criteo CoreID	`CORE_xyz789`	Medium
`yahoo_connect`	Yahoo ConnectID	`YHOO_connect123`	Medium

Geographic Keys

Key Type	Description	Example
`postal_code`	ZIP/Postal codes	`90210`, `SW1A 1AA`
`lat_long`	Latitude/Longitude	`34.0522,-118.2437`
`uk_postal_district`	UK postal districts	`SW12`, `WC1`

Property Keys

Key Type	Description	Example
`domain`	Website domain	`cnn.com`, `bbc.co.uk`
`app_bundle`	Mobile app bundle	`com.example.app`
`property_id`	Custom property ID	`prop_12345`

Composite Keys

Combine multiple key types for more specific targeting:

postal_code,domain - Geographic + Property targeting
maid,domain - User + Property targeting
lat_long,app_bundle - Location + App targeting

Data Ingestion Methods

Best for: Dynamic audience updates, real-time event-based signals, immediate data changesUse the POST endpoints for real-time signal updates:

# Update signals in real-time
curl -X POST https://api.scope3.com/signals/maid \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: text/plain" \
  -d "SET user123 high_value_customer recent_purchaser"

Advanced Features

Signal Definition Management

Create and manage signal metadata with targeting rules using MCP tools or direct API calls.

MCP Tools for Signal Definitions

The Campaign API MCP server provides dedicated tools for managing custom signal definitions:

Tool: create_custom_signalDefine a new custom signal with metadata, key types, and regional clusters:

await createCustomSignal({
  name: "UK Premium News Readers",
  key: "postal_code,domain",
  description: "Users in affluent UK postal codes visiting premium news sites",
  clusters: [
    {"region": "emea-ex-eu", "channel": "ctv"},
    {"region": "emea-ex-eu", "channel": "web"}
  ]
});

Direct API Access

You can also create signal definitions directly via REST API: POST /signal/{signalId}

{
  "key": "postal_code,domain",
  "clusters": [
    {"region": "emea-ex-eu", "channel": "ctv"}, 
    {"region": "emea-ex-eu", "channel": "web"}
  ],
  "name": "UK Premium News Readers",
  "description": "Users in affluent UK postal codes visiting premium news sites"
}

Key Types and Validation

The MCP tools automatically validate key types against supported identifiers: Single Key Types: maid, rampid, postal_code, domain, app_bundle, etc. Composite Key Types: postal_code,domain, maid,domain, lat_long,app_bundle, etc. Invalid key types will be rejected with helpful error messages listing valid options.

EU-specific clusters ensure data residency compliance with dedicated EU infrastructure and GDPR-compliant data processing.

{
  "clusters": [
    {"region": "eu"},
    {"region": "eu"}
  ]
}

Error Handling

HTTP Status Codes

Code	Description
`200`	Success
`400`	Bad Request - Invalid format or parameters
`401`	Unauthorized - Invalid API key
`404`	Not Found - Identifier or signal not found
`429`	Rate Limited - Too many requests
`500`	Internal Server Error

Common Errors

{
  "error": "invalid_operation",
  "message": "Supported operations: SET, ADD, REM, DEL"
}

Rate Limits

Batch Operations: 10,000 identifiers per request maximum

Integration with Campaign Platform

Using Custom Signals in Campaigns

After creating signal definitions with the MCP tools, reference your custom signals in campaign prompts:

const campaign = await createCampaign({
  brandAgentId: "ba_123",
  name: "High-Value Customer Campaign",
  prompt: "Target loyalty_tier_gold and high_value_customer segments interested in premium products",
  budget: { total: 50000, currency: "USD" }
});

Performance Monitoring

Monitor custom signal performance alongside third-party signals:

const signalAnalysis = await analyzeTactics({
  campaignId: "camp_123",
  analysisType: "signals"
});

// Compare custom vs third-party signal effectiveness:
// Custom: loyalty_tier_gold (92% effectiveness)
// Third-party: age_25_34 (76% effectiveness)

Support & Resources

Technical Support

Email SupportGet help with integration questions, API issues, and technical implementation.

Signal Guide

Understanding SignalsLearn how custom signals work with third-party signals in campaign optimization.

For additional resources:

Documentation: https://docs.scope3.com
Status Page: https://status.scope3.com

Overview

Features

Object Guides

Optimization

Integrations

Reporting & Analytics

​Overview

​Key Features

​Custom Signal Types

​Audience Segments

​Geographic Signals

​Property Signals

​Getting Started

​Authentication

​Quick Start Example

​Core Concepts

​Signal Keys

​Data Architecture

Auto-Expiration

Scalable Storage

Secure Access

​API Reference

​Response Formats

​Store/Update Signals

​Retrieve Signals

​Multi-Field Signals

​Supported Key Types

​Identity Keys

​Geographic Keys

​Property Keys

​Composite Keys

​Data Ingestion Methods

​Advanced Features

​Signal Definition Management

​MCP Tools for Signal Definitions

​Direct API Access

​Key Types and Validation

​GDPR Compliance

​Error Handling

​HTTP Status Codes

​Common Errors

​Rate Limits

​Integration with Campaign Platform

​Using Custom Signals in Campaigns

​Performance Monitoring

​Support & Resources

Technical Support

Signal Guide

Overview

Key Features

Custom Signal Types

Audience Segments

Geographic Signals

Property Signals

Getting Started

Authentication

Quick Start Example

Core Concepts

Signal Keys

Data Architecture

API Reference

Response Formats

Store/Update Signals

Retrieve Signals

Multi-Field Signals

Supported Key Types

Identity Keys

Geographic Keys

Property Keys

Composite Keys

Data Ingestion Methods

Advanced Features

Signal Definition Management

MCP Tools for Signal Definitions

Direct API Access

Key Types and Validation

GDPR Compliance

Error Handling

HTTP Status Codes

Common Errors

Rate Limits

Integration with Campaign Platform

Using Custom Signals in Campaigns

Performance Monitoring

Support & Resources