Skip to main content
Skip table of contents

The Trade Desk APIs

Overview

This topic explains how you can integrate 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

Generate a long-lived access token

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

  1. Navigate to https://partner.thetradedesk.com/v3/portal/tokens and select Generate Token.

  2. Give the token a name and configure its lifespan.

  3. 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:

  1. Create a segment

  2. Generate file drop URL

  3. 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.

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

inputBody

file

(Required)

Contact list file. Assigned to PUT body via "Input body from file" option.

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 file 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:

  1. Remove leading and trailing spaces.

  2. If there are uppercase characters, convert them to lowercase.

  3. 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.

Further reading

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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close