The Trade Desk

Send real-time conversion events to The Trade Desk through the Real-Time Conversion Events API.

Why route The Trade Desk through Datafly Signal

• Conversions survive ad blockers and tracking prevention. Signal sends the event from your own infrastructure, so the conversions The Trade Desk optimises against are not filtered by the browser.
• The impression behind each click comes back with the conversion. The Trade Desk’s click-through macros put the impression ID and the visitor’s TDID on your landing page; Datafly.js keeps them first-party and Signal sends them with the conversion, with no third-party cookie involved.
• One consent decision governs every destination. The Trade Desk is gated by the same consent state as the rest of your stack, so a withdrawal applies everywhere at once.
• Presets for Retail and Insurance. The mapping starts from a working configuration for your vertical, and every field can be changed afterwards.

Prerequisites

1. Your TTD Advertiser ID, or for merchant (retail media) event tracking your Merchant ID, from your TTD account manager.
2. The Event Tracker ID the conversions are recorded against (event mapping), or your Universal Pixel ID (URL mapping, where The Trade Desk maps events by page URL).
3. Agree the event names (sitevisit, viewitem, addtocart, purchase, quote, lead and so on) with your TTD account manager: TTD configures the accepted event types per advertiser.

Configuration

The Trade Desk takes an Advertiser ID or a Merchant ID, and an Event Tracker ID or a Universal Pixel ID, never both of a pair. The API needs no authentication.

Configure in Signal

1. In the Management UI, go to Integrations > Integration Library and select The Trade Desk.
2. Choose a preset, fill in the fields above and choose the pipelines and consent categories (advertising destinations default to marketing).
3. Click Install Integration.

Or with the Management API:

curl -X POST http://localhost:8084/v1/admin/integration-catalog/the_trade_desk/install \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "The Trade Desk", "variant": "default", "config": {"advertiser_id": "abcde12", "tracking_tag_id": "tag123abc"}, "delivery_mode": "server_side"}'

Identifiers

The Real-Time Conversion Events API takes one user ID per conversion (adid with adid_type) and, separately, the impression the conversion is attributed to (imp). It has no email or phone field.

Add The Trade Desk’s click-through macros

In The Trade Desk, add these parameters to the landing page (click-through) URL of your creatives. The Trade Desk fills in the values when it serves the ad:

ttdimp=%%TTD_IMPRESSIONID%%&ttd_tdid=%%TTD_TDID%%

For example https://www.example.com/spring-sale?utm_source=ttd&ttdimp=%%TTD_IMPRESSIONID%%&ttd_tdid=%%TTD_TDID%%.

Datafly.js captures both on landing, with nothing to configure. It also reads ttd_imp_id and td_id as the same two values. Signal keeps them under the visitor’s identity, so a purchase on a later page still carries them, and the latest click wins. A TDID of all zeros means the visitor opted out with The Trade Desk, and is ignored.

The Realtime ID sync

To give Signal the TDID of visitors who did not arrive from a click, enable The Trade Desk under Identity → ID Syncs on the pipeline, with the partner ID The Trade Desk issues for its Realtime ID service (ttd_pid). Your TTD account manager provides it; it is not the Partner ID under User Management in The Trade Desk platform.

Once the visitor consents to the sync’s category (marketing unless you choose another), Datafly.js asks The Trade Desk for the visitor’s TDID once per session and sends it to Signal. The TDID lives in The Trade Desk’s third-party cookie, so browsers that block it, Safari among them, return none; the click-through macros cover those visitors. A TDID from a click is used ahead of one from the sync.

What each conversion carries

Signal does not set iattr, which makes The Trade Desk attribute the event to the given impression and bypass its own attribution models, or ivtc, which marks a view-through conversion. Map them in the integration only if your TTD account team asks you to.

API endpoint

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

Authentication: none. Allow egress to insight.adsrvr.org from the network your delivery workers run on.

Presets and event mapping

Every preset sends only the fields it maps (the strict output contract is on). Events not listed are not sent.

Retail (ecommerce)

Retail funnel for TTD Real-Time Conversion Events: sitevisit, searchitem, viewitem, wishlistitem, addtocart, viewcart, startcheckout, purchase with order ID, value, currency and items, and login.

Default (default)

TTD Real-Time Conversion Events core funnel (site visits, product views, add to cart, checkout, leads and purchases) identified by adid/adid_type (TDID, UID2, EUID or device ID), IP and page URL, with the TCF consent string.

Insurance (insurance)

Insurance funnel: quote start, quote requests (quote), leads, application start and policy purchases with premium value and the policy number as order ID. Event names must match the event types your TTD account manager configured.

Deduplication and consent

Purchases carry the order ID as order_id.

Example: purchase (Default preset)

The visitor landed from a Trade Desk ad with ttdimp and ttd_tdid on the URL, then bought on a later page:

datafly.track('purchase', {
  transaction_id: 'T_1001', value: 139.99, currency: 'GBP',
  items: [
    { item_id: 'SKU_1', item_name: 'Helmet', item_category: 'Motorbike', item_brand: 'Shoei', price: 120.00, quantity: 2 },
    { item_id: 'SKU_2', item_name: 'Gloves', price: 19.99, quantity: 1 }
  ]
});

Request Signal sends (rendered from the preset):

{
  "data": [
    {
      "adid": "ttd-uuid-1",
      "adid_type": "TDID",
      "adv": "adv1",
      "client_ip": "203.0.113.7",
      "currency": "GBP",
      "event_name": "purchase",
      "imp": "9f1c2d3e-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
      "items": [
        {
          "cat": "Motorbike",
          "item_brand": "Shoei",
          "item_category": "Motorbike",
          "item_code": "SKU_1",
          "item_id": "SKU_1",
          "item_name": "Helmet",
          "name": "Helmet",
          "price": 120,
          "qty": 2,
          "quantity": 2
        },
        {
          "item_code": "SKU_2",
          "item_id": "SKU_2",
          "item_name": "Gloves",
          "name": "Gloves",
          "price": 19.99,
          "qty": 1,
          "quantity": 1
        }
      ],
      "order_id": "T_1001",
      "referrer_url": "https://shop.example.co.uk/p/123?utm_source=x",
      "tracker_id": "trk1",
      "value": 139.99
    }
  ]
}

Known limitations

• Items carry the source item keys alongside TTD’s item_code, name, qty, price, cat until #1387 is fixed.
• The API has no email or phone field. Visitors are matched by TDID, UID2 or EUID token, device ID and the impression they clicked through from.

Troubleshooting