# The Trade Desk Conversions API

[The Trade Desk](https://www.thetradedesk.com/us) is one of the largest independent demand-side platform (DSP) providing real-time ad pricing and placement for advertisers, ad agencies and brands.\
Using this destination, you can leverage [The Trade Desk Real-Time Conversion Events API](https://api.thetradedesk.com/v3/portal/data/doc/DataConversionEventsApi) to send events via server-side hits.

## Key features

The Trade Desk destination provides the following key features:

* **Events structure**: our [Events reference](https://community.commandersact.com/platform-x/developers/tracking/events-reference) model matches [The Trade Desk's events](https://api.thetradedesk.com/v3/portal/data/doc/DataConversionEventsApi#event-mapping), meaning that your data is properly bridged to the expected fields in an optimized way.
* **Prebuilt mappings**: data mapping for event-based destinations happens automatically, which simplifies user inputs.
* **Smart mapping**: data mapping can be readjusted using your datalayer defined fields.
* **Event mapping**: change standard mapping between your partners' events and yours or add new mappings.
* **Support for multi-item data**: information included in the [item](https://community.commandersact.com/platform-x/developers/tracking/events-reference#item) array is dispatched to The Trade Desk.

## Destination setup

{% hint style="info" %}
On user identifiers, you should pass either `User/Device ID Type` **AND** `User/Device Identifier` **OR** "Smart Mapping" fields like `Device Mobile Identifier` , `The Trade Desk GUID` , `Encrypted UID2 token` , `Encrypted EUID token` , `RampID` but not both.
{% endhint %}

### Configuration

<table><thead><tr><th width="307">Settings</th><th>Description</th></tr></thead><tbody><tr><td><code>TTD Conversion API URL</code></td><td><em><strong><code>Required</code></strong></em><br>Your TTD Conversion API URL. Default: "https://insight.adsrvr.org/track/realtimeconversion".</td></tr><tr><td><code>Tracking Tag Type</code></td><td><em><strong><code>Required</code></strong></em><br>Choose the type of tracking tag. This is either <code>Event Tracking</code> or <code>URL Mapping (page views)</code>.</td></tr><tr><td><code>Merchant Id</code></td><td><em><strong><code>Required for Event Tracking</code></strong></em> <strong>[1]</strong><br>The platform identifier of the merchant assigned by The Trade Desk to the merchant during the onboarding process.</td></tr><tr><td><code>Event Tracker Id</code></td><td><p><em><strong><code>Required for Event Tracking</code></strong></em> <strong>[1]</strong></p><p>The Trade Desk platform identifier of the event tracker.</p></td></tr><tr><td><code>Advertiser Id</code></td><td><em><strong><code>Required for URL Mapping (page views)</code></strong></em> <strong>[1]</strong><br>The Trade Desk platform identifier for the advertiser on whose behalf the tracking call is made.</td></tr><tr><td><code>Universal Pixel Id</code></td><td><em><strong><code>Required for URL Mapping (page views)</code></strong></em> <strong>[1]</strong><br>The Trade Desk platform identifier of the "Universal Pixel".</td></tr><tr><td><code>User/Device ID Type</code></td><td>The type of the advertising identifier, specified in the <code>User/Device Identifier</code>. Supported values: TDID, IDFA, AAID, DAID, NAID, IDL, EUID, or UID2.</td></tr><tr><td><code>User/Device Identifier</code></td><td>The unique advertising identifier for the event. This can be any of the identifiers as specified in the following <a href="https://api.thetradedesk.com/v3/portal/data/doc/DataConversionEventsApi">LINK</a> (See <code>adid</code> property).</td></tr><tr><td><code>TTD TDID Cookie Name</code></td><td>The first party cookie in which you stored the TTD TDID cookie value. This is used when no value can be retrieved from the field<code>User/Device Identifier</code>. Default value: "ttd_TDID".</td></tr><tr><td><code>Custom Event Properties</code></td><td>Map your custom event properties by setting their field names in <code>The Trade Desk property name</code> and adding the field name holding the values in <code>Your value</code> . E.g. if you input <code>size</code> in the <code>The Trade Desk property name</code> and <code>items.0.product.size</code> <strong>[2]</strong> in <code>Your value</code> , you will have a custom event property in The Trade Desk called <code>size</code> with a value based on the content of the field <code>items.0.product.size</code> .</td></tr><tr><td><code>Event Mapping</code></td><td>Change the <a href="#quick-reference">standard mapping</a> between The Trade Desk's events and yours or add new mappings.</td></tr></tbody></table>

{% hint style="info" %}
**1.** See[`Tracking Tag Type`](#configuration)for more details.\
**2.** Using "dots" (".") you can navigate deeper to the specific field you want to get the value of. See [Events reference](https://community.commandersact.com/platform-x/developers/tracking/events-reference) for more details on the standard field names by event. You can also freely set custom fields: there are no boundaries.
{% endhint %}

## Quick reference

{% hint style="info" %}
Using the [Event Mapping](#configuration) you can change the [standard mapping](#quick-reference) between The Trade Desk's events and yours or add new mappings.
{% endhint %}

| Commanders Act Events | The Trade Desk Events  |
| --------------------- | ---------------------- |
| `add_to_cart`         | `addtocart`            |
| `add_to_wishlist`     | `wishlistitem`         |
| `begin_checkout`      | `startcheckout`        |
| `login`               | `login`                |
| `page_view`           | `sitevisit`            |
| `purchase`            | `purchase`             |
| `search`              | `searchitem`           |
| `view_cart`           | `viewcart`             |
| `view_item`           | `viewitem`             |
| `[Any Event]`         | `[Any Event]` **\[1]** |

{% hint style="info" %}
**1.** See [Event Mapping](#configuration) for more details.
{% endhint %}

## Field mappings

{% hint style="info" %}
Properties can be remapped using our [Smart Mapping](https://doc.commandersact.com/features/destinations/advanced-mapping#smart-mapping) feature.\
All The Trade Desk properties on the right column are set in the object <mark style="color:blue;">`data.0`</mark> .
{% endhint %}

{% hint style="warning" %}
The following The Trade Desk properties can be set if `Device OS`, in the "Smart Mapping", is present with supported values:

* `aaid`
* `idfa`
* `naid`
  {% endhint %}

<table><thead><tr><th width="341.6685580062746">Commanders Act Properties</th><th>The Trade Desk Properties</th></tr></thead><tbody><tr><td><code>Merchant Id</code></td><td><code>merchant_id</code> <strong>[*]</strong></td></tr><tr><td><code>Event Tracker Id</code></td><td><code>tracker_id</code> <strong>[*]</strong></td></tr><tr><td><code>Advertiser Id</code></td><td><code>adv</code> <strong>[*]</strong></td></tr><tr><td><code>Universal Pixel Id</code></td><td><code>upixel_id</code> <strong>[*]</strong></td></tr><tr><td><code>User/Device ID Type</code></td><td><code>adid_type</code></td></tr><tr><td><code>User/Device Identifier</code></td><td><code>adid</code></td></tr><tr><td>See <a href="#quick-reference">Quick reference</a></td><td><code>event_name</code> <strong>[1]</strong></td></tr><tr><td><code>context.device.advertising_id</code></td><td><code>daid</code> <strong>[2]</strong><br><code>aaid</code> <strong>[3]</strong><br><code>idfa</code> <strong>[4]</strong><br><code>naid</code> <strong>[5]</strong></td></tr><tr><td><code>partners.ttd.tduid</code></td><td><code>tdid</code> <strong>[6]</strong></td></tr><tr><td><code>partners.ttd.uid2_token</code></td><td><code>uid2_token</code> <strong>[7]</strong></td></tr><tr><td><code>partners.ttd.euid_token</code></td><td><code>euid_token</code> <strong>[8]</strong></td></tr><tr><td><code>partners.ttd.idl</code></td><td><code>idl</code> <strong>[9]</strong></td></tr><tr><td><code>user.country</code></td><td><code>country</code></td></tr><tr><td><code>user.state</code></td><td><code>region</code></td></tr><tr><td><code>user.metro</code></td><td><code>metro</code></td></tr><tr><td><code>user.city</code></td><td><code>city</code></td></tr><tr><td><code>user.zipcode</code></td><td><code>zip</code></td></tr><tr><td><code>context.device.ip</code></td><td><code>client_ip</code></td></tr><tr><td><code>context.page.url</code></td><td><code>referrer_url</code></td></tr><tr><td><code>id</code></td><td><code>order_id</code></td></tr><tr><td><code>value</code></td><td><code>value</code></td></tr><tr><td><code>currency</code></td><td><code>currency</code></td></tr><tr><td><code>partners.ttd.iattr</code></td><td><code>iattr</code> <strong>[10]</strong></td></tr><tr><td><code>partners.ttd.imp</code></td><td><code>imp</code> <strong>[11]</strong></td></tr><tr><td><code>partners.ttd.ivtc</code></td><td><code>ivtc</code> <strong>[12]</strong></td></tr><tr><td><code>partners.ttd.privacy_type</code></td><td><code>privacy_settings.0.privacy_type</code> <strong>[13]</strong></td></tr><tr><td><code>partners.ttd.is_applicable</code></td><td><code>privacy_settings.0.is_applicable</code> <strong>[14]</strong></td></tr><tr><td><code>partners.ttd.consent_string</code></td><td><code>privacy_settings.0.consent_string</code> <strong>[15]</strong></td></tr><tr><td><code>items.X.id</code></td><td><code>items.X.item_code</code></td></tr><tr><td><code>items.X.product.name</code></td><td><code>items.X.name</code></td></tr><tr><td><code>items.X.quantity</code></td><td><code>items.X.qty</code></td></tr><tr><td><code>items.X.product.price</code></td><td><code>items.X.price</code></td></tr><tr><td><code>items.X.product.category_id</code></td><td><code>items.X.cat</code></td></tr><tr><td><code>Custom Event Properties</code></td><td><code>[Custom Property Name]</code> <strong>[16]</strong></td></tr></tbody></table>

{% hint style="info" %}
**\*** See [Configuration](#configuration) for more details on mandatory properties.\
**1.** See [`Event Remapping`](#configuration) for more details.\
**2.** The device advertising identifier for Android, iOS or Windows device.\
**3.** The device advertising identifier for Android device. This is only set if `Device OS` "Smart Mapping" field is set with `Android` (case insensitive).\
**4.** The device advertising identifier for iOS device. This is only set if `Device OS` "Smart Mapping" field is set with `iOS` (case insensitive).\
**5.** The device advertising identifier for Windows device. This is only set if `Device OS` "Smart Mapping" field is set with `Windows` (case insensitive).\
**6.** The Trade Desk 36-character GUID (including dashes) for this user.\
**7.** The encrypted UID2 token, also known as an advertising token. This token is case-sensitive. Tokens are generated and managed using UID2 APIs. More details on the UID2 API/endpoints are available following this [LINK](https://unifiedid.com/docs/endpoints/summary-endpoints).\
**8. T**he encrypted EUID token, also known as an advertising token. This token is case-sensitive. More details on the Unified IDs are available following this [LINK](https://partner.thetradedesk.com/v3/portal/data/doc/UnifiedIDs#id-types).\
**9.** The 49-character or 70-character RampID (previously known as IdentityLink). This must be a RampID from LiveRamp that is mapped specifically for The Trade Desk. More details about mapping a RampID are available following this [LINK](https://sidecar.readme.io/docs/getting-started).\
**10.** A flag that indicates whether the event is attributed to The Trade Desk. If set to <mark style="color:blue;">`true`</mark> (boolean), The Trade Desk attributes the event to the specified impression identifier (See <mark style="color:blue;">`data.0.imp`</mark> ), bypasses The Trade Desk attribution models, and aligns attribution results with those delivered by the partner to advertisers.\
**11.** A 36-character string (including dashes) that serves as the unique identifier for the impression to which the event is attributed.\
**12.** A flag that indicates whether the event is a view-through conversion.\
**13.** This can be one of the following:`GDPR`,`CCPA`or`GPP`depending on the privacy regulation that applies. This is only included if <mark style="color:blue;">`is_applicable`</mark> and <mark style="color:blue;">`consent_string`</mark> are also set. More details are available by following this [LINK](https://api.thetradedesk.com/v3/portal/data/doc/DataConversionEventsApi#properties-privacy).\
**14.** Indicates if the value specified in <mark style="color:blue;">`privacy_type`</mark> is applicable. This either <mark style="color:blue;">`true`</mark> (or <mark style="color:blue;">`1`</mark> ) or <mark style="color:blue;">`false`</mark> (or <mark style="color:blue;">`0`</mark> ), boolean or integer type. This is only included if <mark style="color:blue;">`privacy_type`</mark> and <mark style="color:blue;">`consent_string`</mark> are also set. More details are available by following this [LINK](https://api.thetradedesk.com/v3/portal/data/doc/DataConversionEventsApi#properties-privacy).\
**15.** The user's TCF consent string. This is only included if <mark style="color:blue;">`privacy_type`</mark> and <mark style="color:blue;">`is_applicable`</mark> are also set. More details are available by following this [LINK](https://api.thetradedesk.com/v3/portal/data/doc/DataConversionEventsApi#properties-privacy).\
**16.** See <mark style="color:blue;">`Custom Event Properties`</mark> in [Configuration ](#configuration)for more details on how you can bridge custom properties to The Trade Desk.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.commandersact.com/features/destinations/destinations-catalog/the-trade-desk/the-trade-desk-conversions-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.