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:
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 |
---|---|---|
|
| (Required) Authorized access token. |
|
| (Required)
|
Parameters:
Field | Data Type | Description |
---|---|---|
|
| (Required) Advertiser ID. |
|
| (Required) The geographical region of the CRM data segment based on the origin of PII. |
|
| (Required) The name of the segment. |
Request:
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:
{
"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 |
---|---|---|
|
| (Required) Authorized access token. |
|
| (Required)
|
Parameters:
Field | Data Type | Description |
---|---|---|
|
| (Required) The type of personally identifiable data (PII) sent by the advertiser. Allowed values:
|
|
| (Required) The way the newly uploaded personally identifiable information (PII) is to be merged with the existing data. Allowed values:
|
|
|
|
|
| Time-to-live (TTL) in minutes for the anonymized identifiers generated by the mapping process. If not provided, the default value is |
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:
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:
{
"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 |
---|---|---|
|
| (Required)
|
Parameters:
Field | Data Type | Description |
---|---|---|
|
| (Required) Contact list file. Assigned to |
Request:
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:
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
tojanedoe@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
tojanedoe@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: