Trade Desk & Index Exchange Integration

AudienceGPT supports two major programmatic advertising platforms beyond LiveRamp: The Trade Desk (API-based segment management) and Index Exchange (file-based segment uploads). This guide covers setup, credentials, naming formats, and activation workflows for both platforms.

---

Trade Desk

Overview

The Trade Desk integration uses the Taxonomy Provider API v3 to create, update, and deactivate audience segments on The Trade Desk marketplace. Authentication uses a Bearer token (API key) rather than OAuth.

Prerequisites

1. A Trade Desk Partner account with Taxonomy Provider access
2. An API key from the Trade Desk partner portal
3. Your Provider ID (identifies your data provider account)
4. Optionally, a Brand ID for Data Alliance connections (e.g. "dav2delvrai")
5. The activations auth scope in AudienceGPT

Connection Configuration

Create an outbound connection with the following settings:

Field	Value	Description
Name	e.g. "Trade Desk Production"	Display name
Platform	tradedesk	Platform identifier
Direction	outbound	Push destination
Auth Type	bearer	Uses API key as Bearer token

Credentials

Credential	Description
api_key	Trade Desk API key (used as Bearer token)
provider_id	Your Trade Desk Provider ID
brand_id	(Optional) Brand ID for Data Alliance connections

Connection Config (JSONB)

Config Key	Type	Default	Description
api_base_url	string	https://partners.thetradedesk.com/api/v3	Trade Desk API base URL
default_cpm	number	--	Default CPM price for segments
currency	string	"USD"	Currency code

Example Configuration

{
  "api_base_url": "https://partners.thetradedesk.com/api/v3",
  "default_cpm": 3.00,
  "currency": "USD"
}

Authentication

All Trade Desk API requests use a simple Bearer token:

Authorization: Bearer <api_key>
Content-Type: application/json

No OAuth flow is needed -- the API key is sent directly with each request.

Segment Operations

Create Segment

POST /taxonomy/segment

Request body:

{
  "ProviderId": "your-provider-id",
  "SegmentName": "Business Technology > Cloud Computing > AWS Migration",
  "Description": "Professionals actively researching AWS cloud migration...",
  "BuyableStatus": true,
  "Cpm": 3.00,
  "Currency": "USD"
}

If a brand_id is configured, a BrandId field is included automatically.

Key constraints:

Field	Limit	Notes
SegmentName	255 characters	Truncated automatically
Description	500 characters	Truncated automatically

Update Segment

PUT /taxonomy/segment

The update body includes ProviderId, SegmentId, SegmentName, Description, and optionally BrandId and Cpm.

Deactivate Segment

PUT /taxonomy/segment

Deactivation sends BuyableStatus: false along with ProviderId and SegmentId.

Get Segment

The Trade Desk API returns segments in a hierarchical tree structure. AudienceGPT searches the tree recursively to find a specific segment by ID:

GET /providers/{providerId}/segments

Koa NLP-Optimized Naming

Trade Desk's Koa AI platform processes segment names using NLP to help buyers find relevant audiences. The default Trade Desk output template generates names optimized for Koa discovery:

Parent Category > Subcategory > Topic Name

For example:

Business Technology > Cloud Computing > AWS Migration Services

Koa Optimization Tips

• Lead with the most specific topic information
• Avoid abbreviations that Koa may not recognize
• Include relevant category context for disambiguation
• Keep names descriptive but under the 255-character limit

Description Format

Trade Desk descriptions have a 500-character limit -- more generous than LiveRamp's 245 characters. Descriptions are generated from configurable templates and include segment-type-aware prefixes (B2B/B2C).

Testing the Connection

The test endpoint verifies the API key and Provider ID by fetching the provider's segment tree:

GET /providers/{providerId}/segments

A successful response confirms authentication and provider access.

Retry Behavior

Setting	Value
Max retries	3
Backoff	Exponential (1s, 2s, 4s)
API timeout	30 seconds
Retried errors	429 (rate limit), 5xx (server errors)

---

Index Exchange

Overview

Index Exchange uses a file-based integration model. Unlike Trade Desk and LiveRamp, which have REST APIs for segment management, IX segments are registered and updated by uploading file pairs (metadata JSON + gzipped data) via SFTP or S3.

Prerequisites

1. An Index Exchange account with audience upload access
2. SFTP credentials (host, username, password) or S3 access (bucket, IAM role ARN)
3. Your IX Account ID and Advertiser Account ID
4. Knowledge of the match key type for your data (IP, URL, device ID, etc.)

Connection Configuration

Field	Value	Description
Name	e.g. "Index Exchange SFTP"	Display name
Platform	indexexchange	Platform identifier
Direction	outbound	Push destination
Auth Type	header	Uses SFTP credentials

Credentials (SFTP)

Credential	Description
sftp_host	SFTP server hostname
sftp_username	SFTP username
sftp_password	SFTP password
sftp_port	(Optional) SFTP port, defaults to 22

Connection Config (JSONB)

Config Key	Type	Description
account_id	string	IX account ID (used as ownerAccount_id in meta files)
advertiser_account_id	string	Advertiser account ID for meta files
match_key	string	Match key type: ip, url, deviceid, uid, appbundle, contentid, or postalcode
upload_method	string	sftp or s3
s3_bucket	string	(S3 only) S3 bucket name
s3_role_arn	string	(S3 only) IAM role ARN for S3 access
default_cpm	number	Default CPM price
currency	string	Currency code

Example Configuration (SFTP)

{
  "account_id": "12345",
  "advertiser_account_id": "67890",
  "match_key": "ip",
  "upload_method": "sftp",
  "default_cpm": 1.50,
  "currency": "USD"
}

Example Configuration (S3)

{
  "account_id": "12345",
  "advertiser_account_id": "67890",
  "match_key": "deviceid",
  "upload_method": "s3",
  "s3_bucket": "my-ix-uploads",
  "s3_role_arn": "arn:aws:iam::123456789:role/ix-upload-role",
  "default_cpm": 1.50,
  "currency": "USD"
}

File Format

Each segment upload consists of two files:

Meta File (JSON)

The meta file follows IX's v1.2 schema:

{
  "meta_version": "1.2",
  "audienceName": "Technology > Cloud Computing > AWS Migration",
  "audienceID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "advertiserAccount_id": "67890",
  "ownerAccount_id": 12345,
  "exportTimestamp": "2026-02-25 14:30:00"
}

Data File (Gzip)

The data file contains one match-key value per line, gzip-compressed:

192.168.1.1
10.0.0.1
172.16.0.1

The file is uploaded to a folder determined by the match_key configuration.

Segment Lifecycle

Index Exchange segments work differently from API-based platforms:

Operation	How It Works
Create	Upload meta JSON + data .gz to SFTP/S3
Update	Upload new files with the same audienceID
Deactivate	Stop refreshing data files; segments expire naturally
Get status	Not available via API; tracked internally by AudienceGPT

Natural Expiration

IX segments expire when data files are not refreshed. There is no explicit deactivation API. Ensure your refresh schedule keeps segments active.

Match Key Types

The match key determines which SFTP folder receives the uploaded files:

Match Key	Description	Example Values
ip	IP addresses	192.168.1.1
url	Page URLs	https://example.com/page
deviceid	Mobile device IDs (IDFA/AAID)	A1B2C3D4-E5F6-...
uid	User IDs / cookies	user_abc123
appbundle	App bundle identifiers	com.example.app
contentid	Content identifiers	article_12345
postalcode	Postal/ZIP codes	10001

Testing the Connection

The connection test validates that all required fields are present:

• SFTP host is configured
• SFTP username and password are provided
• Account ID and Advertiser Account ID are set

note

A full SFTP connectivity test (establishing an SSH connection) is planned for a future release. Current validation ensures configuration completeness.

---

Shared Concepts

Push Workflow

Both Trade Desk and Index Exchange follow the same client-orchestrated push architecture used by all AudienceGPT outbound connections:

1. Create push run -- POST /api/connections/{id}/push/run
2. Push batches -- POST /api/connections/{id}/push/run/{runId}/push (25 segments per batch)
3. Poll status -- GET /api/connections/{id}/push/run/{runId}/status

Stale Detection

Stale detection works identically for all platforms. The system compares:

• Pushed name vs. the current template-generated name for the connection's output template
• Engine version at push vs. the topic's current engine version

Stale segments appear in the Data Hygiene dashboard (/hygiene) and can be refreshed individually or in bulk.

Output Templates

Both Trade Desk and Index Exchange naming formats are driven by configurable output templates. Administrators can customize path fields, separators, description templates, and character limits via Admin > Output Templates.

See the Output Templates admin guide for full customization options.

---

Troubleshooting

Trade Desk Errors

Error	Cause	Resolution
Trade Desk returned 401	Invalid API key	Verify the API key in connection credentials
Trade Desk returned 403	Insufficient permissions	Ensure your account has Taxonomy Provider access
Failed to create Trade Desk segment: 400	Invalid request body	Check Provider ID and segment data
Trade Desk API did not return a segment ID	Unexpected API response	The API response format may have changed; check Trade Desk documentation

Index Exchange Errors

Error	Cause	Resolution
SFTP host is required	Missing configuration	Set the sftp_host in connection credentials
SFTP username is required	Missing credential	Provide SFTP username
IX account ID is required	Missing config	Set account_id in connection config
Advertiser account ID is required	Missing config	Set advertiser_account_id in connection config

General Push Errors

Error	Cause	Resolution
Duplicate name already active on connection	Name collision	Two topics generated the same platform name; review template output
Connection not found	Invalid connection ID	Verify the connection exists and belongs to your organization
Run is completed, cannot push	Stale run	Create a new push run

---

API Reference

Endpoint	Method	Description
/api/connections	POST	Create a TTD or IX connection
/api/connections/{id}	GET/PUT/DELETE	Manage connection
/api/connections/{id}/test	POST	Test connection
/api/connections/{id}/push/run	POST	Start 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
/api/activations/{id}/deactivate	POST	Deactivate segment
/api/activations/{id}/refresh	POST	Refresh stale segment

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