The Trade Desk

Datafly Signal delivers conversion events to The Trade Desk server-to-server using the Real-Time Conversion endpoint. This enables accurate attribution for programmatic campaigns running on The Trade Desk’s DSP.

API Endpoint

POST https://insight.adsrvr.org/track/realtimeconversion

Events are sent as JSON. No authentication header is required — authentication is handled via the tracker_id and adv (advertiser ID) in the payload.

Configuration

Management UI Setup

1. Go to Integrations > Add Integration > The Trade Desk.
2. Enter your advertiser_id, tracker_id, and ttd_pid.
3. Select consent categories (typically advertising).
4. Click Save.

Management API Setup

curl -X POST http://localhost:8084/v1/admin/integrations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_abc123",
    "vendor": "the_trade_desk",
    "name": "Trade Desk Conversions",
    "enabled": true,
    "config": {
      "advertiser_id": "abc12345",
      "tracker_id": "your_tracker_id",
      "ttd_pid": "your_partner_id"
    },
    "consent_categories": ["advertising"]
  }'

Identity: TDID Resolution

The Trade Desk uses the TDID (Trade Desk ID) as its primary identity for conversion attribution. Unlike other platforms that accept click IDs or hashed emails directly, The Trade Desk requires server-side resolution of the TDID.

How TDID Resolution Works

1. When a visitor first arrives on your site, Datafly Signal calls The Trade Desk’s match service server-side to resolve the visitor’s TDID.
2. The match service uses the visitor’s IP address and User-Agent to return a TDID (if a match is found).
3. The TDID is stored in the Identity Hub and included in all subsequent conversion events for that visitor.

Match Service Endpoint

GET https://match.adsrvr.org/track/rid?ttd_pid={pid}&fmt=json

The match request includes the visitor’s IP and User-Agent as forwarded headers:

curl "https://match.adsrvr.org/track/rid?ttd_pid=your_partner_id&fmt=json" \
  -H "X-Forwarded-For: 203.0.113.50" \
  -H "User-Agent: Mozilla/5.0 ..."

Response:

{
  "TDID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "AdvertiserTDID": "f1e2d3c4-b5a6-0987-dcba-0987654321fe"
}

Match Rate

Not all visitors will have a TDID. The match rate depends on:

• Whether the visitor has previously interacted with Trade Desk-served ads.
• Cookie availability and browser privacy settings.
• Geographic region.

Events without a resolved TDID can still be sent but will have limited attribution capability.

Event Mapping

The Trade Desk uses custom conversion event names tied to your tracker configuration. All conversion events are mapped based on the tracker_id.

Example: Conversion Event

Datafly.js call:

_df.track("Order Completed", {
  order_id: "ORD-001",
  total: 129.99,
  currency: "USD"
});

Trade Desk Real-Time Conversion payload sent by Datafly:

{
  "data": [
    {
      "tracker_id": "your_tracker_id",
      "adv": "abc12345",
      "event_name": "purchase",
      "value": 129.99,
      "currency": "USD",
      "order_id": "ORD-001",
      "td1": "ORD-001",
      "items": [
        {
          "item_code": "SKU-A",
          "name": "Widget",
          "qty": 2,
          "price": 49.99
        }
      ],
      "imp": "evt_abc123def456",
      "tdid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "client_ip": "203.0.113.50",
      "referrer_url": "https://example.com/checkout/confirmation"
    }
  ]
}

Example: Page View (for Attribution)

{
  "data": [
    {
      "tracker_id": "your_tracker_id",
      "adv": "abc12345",
      "event_name": "pageview",
      "tdid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "client_ip": "203.0.113.50",
      "referrer_url": "https://example.com/products/widgets"
    }
  ]
}

Custom Data Parameters

The Trade Desk supports custom data fields (td1 through td10) for passing additional conversion metadata:

Configure custom field mappings in the integration configuration:

{
  "config": {
    "advertiser_id": "abc12345",
    "tracker_id": "your_tracker_id",
    "ttd_pid": "your_partner_id",
    "custom_fields": {
      "td1": "order_id",
      "td2": "product_category"
    }
  }
}

API Response

A successful response from The Trade Desk:

HTTP 200 OK

The Real-Time Conversion endpoint returns a 200 status code with an empty body on success.

An error response:

{
  "error": "Invalid tracker_id",
  "error_code": "INVALID_TRACKER"
}

Rate Limits