The Trade Desk APIs

Overview

This topic explains how you can integrate Redpoint Interaction (RPI), Redpoint Data Management (RPDM), and The Trade Desk’s (TTD) APIs to create segments and upload contact lists to those created segments.

Basic requirements

Each task contained in this documentation has the following requirements:

A TTD account
A corresponding API token
An Advertiser ID

Integration

Set up RPI templates

Create TTD onboarding template

In RPI, create a new export template and name it “The Trade Desk Onboarding”. This template will expose Redpoint CDP Email Address and Phone attributes for uploading to TTD.
Drag Redpoint CDP attributes Email Address and Phone into the Attribute column.
Add the Channel Execution ID attribute from the Offer History table.

Create outbound channels

In RPI, create a new channel.
Set the channel to Data Extract.
Name the channel “The Trade Desk Onboarding”.

Navigate to the Channel Specific tab and set the export template to The Trade Desk Onboarding.
Next, set the Location type under Extract Location to Database table.
Under Extract Table Name check Use custom format and set the Custom format to RPI_TTD.
Navigate to the Post Execution tab in the Channels Configuration screen.
Check the Post-execution checkbox to call a service URL after channel execution. Enter your RPDM web service URL.

Set up TTD components in RPDM

UploadToSegment.dlb

The archive containing the RPDM artifacts to support the TTD integration requires updating some of the project parameters. After importing the artifacts into RPDM, open the project named UploadToSegmentand update the following project parameters. See API endpoint information further down for explanation of some of the project parameters.

token: see below for generating a long-lived access token.
advertiserId: your TTD advertiser ID.
baseUrl: defaults to the base TTD API URL https://api.thetradedesk.com/v3/. Updating may require other changes.
logOutputRoot: folder base path for web service logs.
region: defaults to US.
segmentName: the name of the segment to create.
mergeMode: defaults to Replace.
piiType: defaults to Email.
retentionEnabled: defaults to false.

By default, the project is set up to import unhashed Emails. If you would like to switch to importing Phone Numbers, then you must update the JSON that is output from PayloadJSONOutput widget and PayloadCleaner widget.

Make project a webservice

To expose the RPDM project to The Trade Desk Onboarding channel, right- on the project and select Make a Webservice. Configure the information for the webservice login, Server, URL path, and TCP/IP port. The URL path must match the suffix of the Service URL in the Post Execution tab of the Channel. Additionally, the ports must match. Make sure the webservice is enabled in RPDM before testing.

Using the integration

The Outbound Delivery Trade Desk channel can now be leveraged within RPI workflows. Follow the standard practices for creating selection rules and audiences in RPI, and building associated workflow schedules and triggers.

To enable the sync of an RPI Audience output to The Trade Desk, create an outbound delivery offer and associate it to The Trade Desk Onboarding channel.

Once the workflow has executed successfully in RPI, the orchestration and CDP data sourced from RPI can now be used in The Trade Desk.

Generate a long-lived access token

To generate a long-lived access token for TTD API:

Navigate to https://partner.thetradedesk.com/v3/portal/tokens and select Generate Token.
Give the token a name and configure its lifespan.
Make sure to copy the token; once you close the modal, you will not be able to access the token value again.

Usage flow

The process to create a segment and upload a contact list to it is comprised of three steps:

Create a segment.
Generate file drop URL.
Post contact list to drop URL.

Create a segment

Endpoint

https://api.thetradedesk.com/v3/crmdata/segment

Method

POST

Header

Field	Data type	Description
`TTD-Auth`	`string`	(Required) Authorized access token.
`Content-Type`	`string`	(Required) `application/json`.

Parameters

Field	Data type	Description
`advertiserId`	`string`	(Required) Advertiser ID.
`region`	`string`	(Required) The geographical region of the CRM data segment based on the origin of PII.
`segmentName`	`string`	(Required) The name of the segment.
`dataProviderId`	`string`	The `DataProviderId`, only to be specified by 3rd party integrations. Contact your Technical Account Manager for details. Example: `redpoint`

Request

CODE

POST /v3/crmdata/segment HTTP/1.1
Host: api.thetradedesk.com:443
TTD-Auth: qqK9rHhHPGY3/xn859nrnKPpWU/WMuI0I3RfdFEHlAzmsJcihBZE1kNr0SezKiLD
Content-Type: application/json
Content-Length: 85

{  
  "advertiserId" : "qxwcdxw", 
  "region" : "US", 
  "segmentName" : "Segment" 
}

Response

CODE

{
  "FirstPartyDataId":358268865,
  "CrmDataId":"cc9b84o"
}

A successful response returns a 200 code with the CrmDataId used in the following step to create a drop URL to post the contact list to.

Generate drop URL

Endpoint

https://api.thetradedesk.com/v3/crmdata/segment/{advertiserId}/{CrmDataId}

Method

POST

Header

Field	Data type	Description
`TTD-Auth`	`string`	(Required) Authorized access token.
`Content-Type`	`string`	(Required) `application/json`.

Parameters

Field	Data type	Description
`piiType`	`string`	(Required) The type of personally identifiable data (PII) sent by the advertiser. Allowed values: `Email` `EmailHashedUnifiedId2` `Phone` `PhoneHashedUnifiedId2`
`mergeMode`	`string`	(Required) The way the newly uploaded personally identifiable information (PII) is to be merged with the existing data. Allowed values: `Add` `Replace`
`retentionEnabled`	`bool`	If set to `true`, PII data is retained in hashed form for 90 days and is refreshed daily as UIDs decay. If set to `false`, PII data is processed once and then discarded. If not provided, the default value is `false`.
`ttlInMinutes`	`int`	Time-to-live (TTL) in minutes for the anonymized identifiers generated by the mapping process. If not provided, the default value is `129600` minutes (90 days).

The uploaded contact list must match the piiType defined during the drop URL creation process. If raw emails or phone numbers are sent, TTD will handle the hashing on their end. If hashed emails or phone numbers are sent, they must be normalized, SHA-256 hashed, and Base64 encoded. See more at https://partner.thetradedesk.com/v3/portal/data/doc/DataPiiNormalization.

Request

CODE

POST /v3/crmdata/segment/qxwcdxw/cc9b84o HTTP/1.1
Host: api.thetradedesk.com:443
TTD-Auth: qqK9rHhHPGY3/xn859nrnKPpWU/WMuI0I3RfdFEHlAzmsJcihBZE1kNr0SezKiLD
Content-Type: application/json
Content-Length: 79

{  
  "mergeMode" : "Replace", 
  "piiType" : "Email", 
  "retentionEnabled" : "false" 
}

Response

CODE

{
  "ReferenceId":"153e6cc3-1979-4b9f-991b-46fde567afa9",
  "Url":"https://thetradedesk-crm-data.s3.us-east-1.amazonaws.com/data/advertiser/qxwcdxw/drop/153e6cc3-1979-4b9f-991b-46fde567afa9/pii?X-Amz-Security-Token=IQoJb3JpZ2luX2VjED8aCXVzLWVhc3QtMSJGMEQCIFxeF2giAGAnXNBCT%2Fpz2Y3icv1PktW57yDXHcUVDCFiAiBhHjV1LCF4cLpYDp0E8cj%2Bt6pIQ%2BnJfGcOzzfIHDFbcSqXBQio%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAIaDDYzOTM0MzM2NTcyMCIMmleUDV4803pTWsfvKusENB8%2B1Ixz4JqPzSfMmk9UC%2BDyFZ5ifjfKJFqtjBkFj0KUUSAd4T3MeEcG6u8F4wIPFGMYJi4ijYkNbKJ5Jjj05bBnwIpp6TIFuxFzhKIFA7mSVWORI%2FWFfR7QLAPPTAwu7qiigzhum%2Fd6o8qMfzKkiY9hkR9UZSNvan80fMBHVqfKz6yk8cemmOwJPbsloyjicECsx6zCBT%2F6EJMFaKtDl1jlruiWWkVjA0y%2FCd0jl3eG%2FGqWgCmyrhZMrQ6kDDkaGXdvy%2BhJYH1ZEHa9zFcxnsX7QM9HMPHHhTHsY%2Bcbr2ZcDtflsoF70g5xp8nghqcpc1RWrkjaWj%2Bs9Y1HMMCBn3Pjbob%2FkvuK9KEbaNwJiUrStPrK9zx7BPdvXePjwUVE%2Fa%2FhbhXKvE8TU%2Fqb8Q1HE3%2BQLlyEX8qqmVFbr8G%2B86dldkphviMW%2BxQvPq4Ei1DsAY%2Bv1Vpd5LFAlNk%2Frah2xQRz6xGl%2BMip5doZF6DwKX1wmjjmY3P47tg7h%2BbJQaBMOGDcaY6TrqjEBIKp0TNn6p%2BB0q0qjFz0hR3Tn5kmX8AYksxXAzrBS%2FA3xGLH7xDN96cb4wbWSBKXJdbAhqtzhiWCnPdNh4dwm%2BVl1emAcAUpIhdOVyQm3zC5bonhixjXGVkwqSjypEtu1Lcn0gIWDFc2dD84lgRZIb8aZEo5a3B4LUofv6rYSPdwFA%2FEo2fRjx0d4mub%2Bcqt4qiMOz3FRvNB%2BIZQj%2BNOZX1cCswab2OXG%2Bsy3wcmtmb%2FRT3X3yrJpS5VT69Bftq6NnN50%2F9mP7Ai5tLGJAJjneYricKPjfPBjXtfGQEQU%2BokODCgkZOyBjqcAblygNHWaKHM0jjr4Bc%2FZNDO1x%2FnHjWr7tbZ8JTKOUY8BmoiNkh2uLA9fnmmVBetawgj%2BJrb8nT6i0Qxy4GDm6pvQ90ErYStIqqp5LiFe6AmJM4TTugDcSS4Vt3gsN8wrUrKvP3dSKCeIvgd0hhQZH3N%2FeW4UWTkXiN7NYE6ssT%2FMxftzwnxbZ0jl0gvzcSKVmAxMeBU%2BRT7b6GfmA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240515T150911Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=ASIAZJW6VRZMOETVPG6E%2F20240515%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=731ed458f044b8b549490a9fc01e343f9eb1a35e11ee31cdde9d03b9aa00d400"
}

A successful response returns a 200 code with the Url field, a signed URL where personally identifiable information (PII) is to be sent securely for processing. The drop URL auto-expires within an hour. You can use it only once, even if it is still live.

Post contact list to drop URL

Endpoint

{Url} field returned in previous step.

Method

PUT

Header

Field	Data type	Description
`Content-Type`	`string`	(Required) `text/plain`

Parameters

Field	Data type	Description
`output`	`string`	(Required) Contact list in string format. Comes from reading DB records and converting them to a one-contact-per-line string payload.

Request

CODE

PUT /data/advertiser/qxwcdxw/drop/153e6cc3-1979-4b9f-991b-46fde567afa9/pii?X-Amz-Security-Token=IQoJb3JpZ2luX2VjED8aCXVzLWVhc3QtMSJGMEQCIFxeF2giAGAnXNBCT%2Fpz2Y3icv1PktW57yDXHcUVDCFiAiBhHjV1LCF4cLpYDp0E8cj%2Bt6pIQ%2BnJfGcOzzfIHDFbcSqXBQio%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAIaDDYzOTM0MzM2NTcyMCIMmleUDV4803pTWsfvKusENB8%2B1Ixz4JqPzSfMmk9UC%2BDyFZ5ifjfKJFqtjBkFj0KUUSAd4T3MeEcG6u8F4wIPFGMYJi4ijYkNbKJ5Jjj05bBnwIpp6TIFuxFzhKIFA7mSVWORI%2FWFfR7QLAPPTAwu7qiigzhum%2Fd6o8qMfzKkiY9hkR9UZSNvan80fMBHVqfKz6yk8cemmOwJPbsloyjicECsx6zCBT%2F6EJMFaKtDl1jlruiWWkVjA0y%2FCd0jl3eG%2FGqWgCmyrhZMrQ6kDDkaGXdvy%2BhJYH1ZEHa9zFcxnsX7QM9HMPHHhTHsY%2Bcbr2ZcDtflsoF70g5xp8nghqcpc1RWrkjaWj%2Bs9Y1HMMCBn3Pjbob%2FkvuK9KEbaNwJiUrStPrK9zx7BPdvXePjwUVE%2Fa%2FhbhXKvE8TU%2Fqb8Q1HE3%2BQLlyEX8qqmVFbr8G%2B86dldkphviMW%2BxQvPq4Ei1DsAY%2Bv1Vpd5LFAlNk%2Frah2xQRz6xGl%2BMip5doZF6DwKX1wmjjmY3P47tg7h%2BbJQaBMOGDcaY6TrqjEBIKp0TNn6p%2BB0q0qjFz0hR3Tn5kmX8AYksxXAzrBS%2FA3xGLH7xDN96cb4wbWSBKXJdbAhqtzhiWCnPdNh4dwm%2BVl1emAcAUpIhdOVyQm3zC5bonhixjXGVkwqSjypEtu1Lcn0gIWDFc2dD84lgRZIb8aZEo5a3B4LUofv6rYSPdwFA%2FEo2fRjx0d4mub%2Bcqt4qiMOz3FRvNB%2BIZQj%2BNOZX1cCswab2OXG%2Bsy3wcmtmb%2FRT3X3yrJpS5VT69Bftq6NnN50%2F9mP7Ai5tLGJAJjneYricKPjfPBjXtfGQEQU%2BokODCgkZOyBjqcAblygNHWaKHM0jjr4Bc%2FZNDO1x%2FnHjWr7tbZ8JTKOUY8BmoiNkh2uLA9fnmmVBetawgj%2BJrb8nT6i0Qxy4GDm6pvQ90ErYStIqqp5LiFe6AmJM4TTugDcSS4Vt3gsN8wrUrKvP3dSKCeIvgd0hhQZH3N%2FeW4UWTkXiN7NYE6ssT%2FMxftzwnxbZ0jl0gvzcSKVmAxMeBU%2BRT7b6GfmA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240515T150911Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=ASIAZJW6VRZMOETVPG6E%2F20240515%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=731ed458f044b8b549490a9fc01e343f9eb1a35e11ee31cdde9d03b9aa00d400 HTTP/1.1
Host: thetradedesk-crm-data.s3.us-east-1.amazonaws.com
Content-Type: text/plain
Content-Length: 35207

bschuppe@yahoo.com
russparker@ziemann.biz
gbahringer@hotmail.com

Response

A successful response returns a 200 code with an empty body.

The Webservice widget in RPDM must have the “No port in Host header” Advanced Headers option checked under the Options tab. Failure to do so will result in an authorization error with mismatched signatures from the Amazon Storage service.

Contact list file requirements

The contact list must contain only either emails or phone numbers.
The data may be in either raw format or hashed and encoded.
The file must contain at least 1500 unique users.
There is no limit for the drop size. However, to ensure faster processing, it is recommended to upload the segment in one drop containing no more than 500 million records. This limits the ingestion to less than an hour.

Hashing and encoding contact data

If you want to hash and encode your own contact data, you must follow these steps:

Normalize the Data

To normalize an email address, complete the following steps:

Remove leading and trailing spaces.
If there are uppercase characters, convert them to lowercase.
In gmail.com addresses only:
- If there is a period (.) in the address (ASCII decimal code 46/UTF-8 hexadecimal code 2E) before the @gmail.com, remove it.
  For example, normalize jane.doe@gmail.com to janedoe@gmail.com.
- If there is a plus sign (+) with an additional string after it before the @gmail.com, remove the plus sign (+) (ASCII decimal code 43/UTF-8 hexadecimal code 2B) and all subsequent characters.
  For example, normalize janedoe+home@gmail.com to janedoe@gmail.com.

To normalize a phone number, make sure it adheres to the E.164 format. Normalized E.164 phone numbers use the following syntax: [+][country code][subscriber number including area code] (with no spaces, hyphens, parentheses, or other special characters). Examples:

US: 1 (123) 456-7890 is normalized to +11234567890.
Singapore: 65 1243 5678 is normalized to +6512345678.
Sydney, Australia: (02) 1234 5678 is normalized to drop the leading zero for the city plus include the country code: +61212345678.

Hash the data

The normalized data must be SHA-256 hashed and then Base64 encoded. The data is first normalized, then hashed using the SHA-256 hashing algorithm, and then the resulting bytes of the hash value are encoded using Base64 encoding. Note that the Base64 encoding is applied to the bytes of the hash value, not the hex-encoded string representation.

Additional resources

For more information on TTD APIs and contact data requirements, refer to the following: