LiveRamp Integration

AudienceGPT integrates with the LiveRamp Data Marketplace Provider API v1 to push classified audience segments directly into LiveRamp's data marketplace. This guide covers connection setup, authentication, the segment push workflow, naming requirements, stale detection, and troubleshooting.

Overview

The LiveRamp integration is an outbound connection that enables you to:

• Create, update, and deactivate segments on LiveRamp's Data Marketplace
• Attach CPM pricing to each segment at push time
• Detect stale activations when segment names or engine versions drift
• Refresh stale segments in bulk or individually

---

Prerequisites

Before configuring the LiveRamp connection, you need:

1. A LiveRamp Data Marketplace Provider account
2. OAuth2 credentials from LiveRamp (client ID, username, password)
3. Your LiveRamp Organization ID (LR-Org-ID header value)
4. A configured Data Source Location in your LiveRamp account
5. The activations auth scope in AudienceGPT (assigned to your user role)

---

Connection Configuration

Creating the Connection

Navigate to Connections in AudienceGPT and create a new outbound connection with the following settings:

Field	Value	Description
Name	e.g. "LiveRamp Production"	Display name for this connection
Platform	liveramp	Platform identifier
Direction	outbound	LiveRamp is a push destination
Auth Type	oauth2	Uses OAuth2 password grant

Credentials

Credentials are encrypted at rest using pgcrypto symmetric encryption and are never exposed to the client.

Credential	Description
client_id	OAuth2 client ID issued by LiveRamp
username	LiveRamp service account username
password	LiveRamp service account password
org_id	LiveRamp Organization ID (sent as LR-Org-ID header)

Connection Config (JSONB)

The connection's config field stores platform-specific settings:

Config Key	Type	Default	Description
token_url	string	https://serviceaccounts.liveramp.com/authn/v1/oauth2/token	OAuth2 token endpoint
api_base_url	string	https://api.liveramp.com	LiveRamp API base URL
default_cpm	number	--	Default CPM price for segments (USD)
currency	string	"USD"	Currency code for pricing
data_source_location	string	--	Data source location identifier in LiveRamp

Example Configuration

{
  "token_url": "https://serviceaccounts.liveramp.com/authn/v1/oauth2/token",
  "api_base_url": "https://api.liveramp.com",
  "default_cpm": 2.50,
  "currency": "USD",
  "data_source_location": "my-data-source"
}

---

Authentication

OAuth2 Password Grant Flow

AudienceGPT authenticates with LiveRamp using the OAuth2 password grant (also called Resource Owner Password Credentials). The flow works as follows:

1. AudienceGPT sends a POST request to the token endpoint with credentials
2. LiveRamp returns an access token with an expiration time
3. The token is cached per-credential key (username:client_id) to ensure tenant isolation
4. Tokens are refreshed automatically 60 seconds before expiry

Token request parameters:

Parameter	Value
grant_type	password
username	Service account username
password	Service account password
scope	openid
client_id	OAuth2 client ID
response_type	token

The token endpoint returns:

{
  "access_token": "eyJhbGci...",
  "expires_in": 3600
}

Token Caching

Tokens are cached in memory per serverless invocation. In multi-tenant environments, the cache key is derived from the credential pair (username:client_id) to prevent cross-org token leakage.

Request Authentication

All API requests include two authentication headers:

Authorization: Bearer <access_token>
LR-Org-ID: <org_id>
Content-Type: application/json

---

Segment Push Workflow

How It Works

The segment push follows a client-orchestrated, batched architecture:

1. Create a push run -- POST /api/connections/{id}/push/run creates an activation run and pending activation records for each selected segment.
2. Push batches -- POST /api/connections/{id}/push/run/{runId}/push processes the next batch of 25 pending activations.
3. Poll status -- GET /api/connections/{id}/push/run/{runId}/status returns progress and completion state.

Segment Creation

For each pending activation, AudienceGPT calls the LiveRamp Provider API:

POST /data-marketplace/provider-api/v1/segments

Request body:

{
  "name": "Technology-Telecom > Business Technology > Cloud Computing",
  "description": "Professionals researching cloud computing solutions...",
  "type": "SYNDICATED",
  "dataSourceLocation": "my-data-source",
  "enabled": true,
  "pricing": {
    "currencyCode": "USD",
    "digitalAdTargeting": 2.50
  }
}

Key constraints:

Field	Limit	Notes
name	250 characters	Truncated automatically
description	245 characters	Truncated automatically
type	Always SYNDICATED	For Data Marketplace segments

Segment Update

Updates use the PUT method on the segment endpoint:

PUT /data-marketplace/provider-api/v1/segments/{segmentId}

The update payload includes name, description, and optionally updated pricing.

Segment Deactivation

Deactivation sets enabled: false on the segment:

PUT /data-marketplace/provider-api/v1/segments/{segmentId}
{
  "enabled": false
}

---

Naming Format

AudienceGPT generates LiveRamp segment names using configurable output templates. The default LiveRamp template produces a hierarchical path format:

Group > Parent Category > Subcategory > Topic

For example:

Technology-Telecom > Business Technology > Cloud Computing > AWS Migration Services

Description Format

Descriptions are generated from templates with a segment-type-aware prefix:

• B2C segments: Consumer-focused description prefix
• B2B segments: Professional/business-focused description prefix
• B2B2C segments: Mixed audience description prefix

Descriptions are truncated to 245 characters to comply with LiveRamp's limit.

Customizing Templates

Administrators can customize LiveRamp naming via Admin > Output Templates. Templates use {{field}} placeholders resolved from classification data:

Placeholder	Description	Example
{{topic}}	Topic name	"AWS Migration Services"
{{group}}	Taxonomy type (shortened)	"Technology-Telecom"
{{category}}	Parent category (shortened)	"Business Technology"
{{subcategory}}	Subcategory	"Cloud Computing"
{{audience_tag}}	B2B/B2C audience tag	"Business"
{{intent}}	Primary intent signal	"Product Intent"
{{journey}}	Buyer journey stage	"High-Intent"
{{user_behavior}}	Derived user behavior	"Intent"

See the Output Templates admin guide for full customization details.

---

CPM Pricing

Each connection has a default_cpm value that applies to all segments pushed through it. Pricing is sent to LiveRamp at segment creation time:

{
  "pricing": {
    "currencyCode": "USD",
    "digitalAdTargeting": 2.50
  }
}

• Currency is set per-connection (default: USD)
• CPM is applied uniformly to all segments on the connection
• Per-segment pricing overrides are not currently supported; use separate connections for different price tiers

Cost Tracking

The admin usage dashboard at /admin/usage tracks internal classification costs, sale prices, and margin per organization. See Pricing Configuration for details.

---

Stale Detection

AudienceGPT continuously monitors pushed segments for staleness -- a condition where the segment name or engine version on the platform no longer matches the current classification data.

What Triggers Staleness

An activation is considered stale when either:

1. Name drift -- The pushed_name stored at push time differs from the current platform name generated by the template engine
2. Version drift -- The engine_version_at_push differs from the topic's current engine_version (classification logic has been updated)

How Detection Works

Stale detection runs as a read-time SQL JOIN query -- no background write cascades. When you view activations, the system compares:

• pushed_name vs. the current template-generated name for the connection's platform
• engine_version_at_push vs. the topic's current engine_version

Refreshing Stale Activations

Stale activations can be refreshed in three ways:

1. Individual refresh -- POST /api/activations/{id}/refresh pushes the updated name to the platform
2. Bulk refresh -- The Data Hygiene page (/hygiene) has a "Refresh All Stale" button
3. CLI script -- bun run refresh-activations processes all stale activations across all orgs

# Preview stale activations without making changes
bun run refresh-activations --dry-run

# Refresh up to 50 stale activations
bun run refresh-activations --limit 50

---

Retry and Timeout Behavior

The LiveRamp client includes built-in resilience:

Setting	Value	Description
Max retries	3	Retries on 429 (rate limit) and 5xx errors
Backoff	Exponential (1s, 2s, 4s)	Delay between retry attempts
API timeout	30 seconds	Per-request timeout
Auth timeout	10 seconds	OAuth token request timeout
Token buffer	60 seconds	Refresh token this many seconds before expiry

Client errors (4xx except 429) are not retried -- they indicate a request problem that needs to be fixed.

---

Troubleshooting

Common Errors

Error	Cause	Resolution
LiveRamp token request failed (401)	Invalid OAuth credentials	Verify client_id, username, and password in connection credentials
LiveRamp token request failed (403)	Account lacks Provider API access	Contact LiveRamp to enable Data Marketplace Provider API for your account
LiveRamp API POST /segments failed (400)	Invalid segment data	Check that dataSourceLocation is valid and name is under 250 chars
LiveRamp API POST /segments failed (409)	Duplicate segment name	A segment with this name already exists; update instead of create
LiveRamp API POST /segments failed (429)	Rate limited	The client retries automatically; if persistent, reduce batch frequency
Duplicate name already active on connection	Name collision	Two topics generated the same platform name; review template configuration
Cannot delete connection with active activations	Active segments exist	Deactivate all segments before deleting the connection

Testing the Connection

After configuring credentials and config, use the Test Connection button or call:

POST /api/connections/{id}/test

This sends a lightweight GET request to the segments endpoint (?limit=1) to verify that authentication succeeds and the API is reachable.

Verifying Pushed Segments

After a successful push, you can verify segments in two places:

1. AudienceGPT Destinations (/destinations) -- Shows activation status, push timestamps, and stale indicators
2. LiveRamp Data Marketplace Portal -- Log in to verify segments appear in your provider inventory

Checking for Stale Activations

Navigate to Data Hygiene (/hygiene) to see a summary of stale activations. The hygiene dashboard shows:

• Number of stale activations per connection
• Which segments have name drift vs. version drift
• One-click refresh for individual segments or bulk refresh for all

---

API Reference

Endpoint	Method	Description
/api/connections	POST	Create a LiveRamp connection
/api/connections/{id}	GET	Get connection details
/api/connections/{id}	PUT	Update connection config
/api/connections/{id}	DELETE	Delete connection (no active segments)
/api/connections/{id}/test	POST	Test connection credentials
/api/connections/{id}/push/run	POST	Start a push run
/api/connections/{id}/push/run/{runId}/push	POST	Push next batch
/api/connections/{id}/push/run/{runId}/status	GET	Poll run status
/api/activations	GET	List activations (filterable)
/api/activations/{id}/deactivate	POST	Deactivate a segment
/api/activations/{id}/refresh	POST	Refresh a stale segment

For full request/response schemas, see the API Reference.