Making Data API calls

To upload data to The Trade Desk platform using the Data API, authenticate each request with an API token and choose a data center.

NOTE: Token authentication is the standard method for all Data API calls. If your account currently authenticates with secret keys, update your integration to use tokens instead.

To call a Data API endpoint, you need the following:

API credentials from your Account Manager.
An API token, generated and placed in the header of your request.

To generate a token, follow the Create an API token instructions.

Create an API token

You can create tokens with a lifetime range of one week to one year using the OpenTTD access management app.

To generate an API token, complete the following steps:

Log in with your The Trade Desk account credentials.
Navigate directly to the OpenTTD Access Management app.
Click Generate Token / Key. The Generate API Token dialog appears.
Enter a descriptive name for your token. For example, include the tool name for which it will be used or any other details that will help you distinguish between multiple tokens later.
In the Application field, select Platform API.
Select the token lifetime based on your key rotation strategy and integration needs.
Click Save. A confirmation message appears with an API token.
Copy the displayed API token, save it to your secrets management system for future reference, and then close the message.
Include the token as the TTD-Auth value in the headers of all API calls that use tokens, for instance, as shown in the following example.

Content-Type: application/json
TTD-Auth: IBqLpJBhK/UnugaMLo56tUittjoBsjG1KCZ0FxxkIoY=

IMPORTANT: Save your API token in your secrets management system, you cannot retrieve or regenerate the same token. If you lose it, you must create a new token.

To change the lifetime of a token or otherwise update it, you need to revoke it, generate a new token, and then replace the tokens in your integration. For details, see Platform authentication.

Data centers

NOTE: Privacy-related restrictions may apply to certain locations and types of data.

The following table lists the URLs and locations of the first-party data servers to which you can upload your data:

Location	Base URL	Notes
APAC	`https://sin-data.adsrvr.org`	None.
Tokyo	`https://tok-data.adsrvr.org`	None.
US East Coast	`https://use-data.adsrvr.org`	None.
US West Coast	`https://usw-data.adsrvr.org`	None.
UK/EU	`https://euw-data.adsrvr.org`	There are certain types of data that do not replicate to this location.
China	`https://data-cn2.adsrvr.cn`	This is specifically for data providers whose data originates from China. This location will not replicate to locations outside of China.

Here's what you need to know about uploading data:

For reduced latency, upload your data to the hostname closest to the location of the users targeted by your campaign. After a short delay, we replicate the data to other data centers globally.
Do not upload the same data to more than one of these data centers. There are exceptions for certain data types such as IP addresses and how they replicate to countries with specific privacy regulations.

Secret keys and signature headers (legacy)

NOTE: To authenticate to the Data API, you must use token authentication or, for certain data providers, OAuth 2.0. Secret keys and signature headers are legacy authentication methods.

To make a call to the appropriate Data API endpoint, you must encode the body of your request with your secret key using the correct signature header type in the request.

Secret keys

When you send data, the included secret key is validated against the secret key the platform has on file for the advertiser ID that you specify in the request. Here's what you need to know about secret keys:

In The Trade Desk platform, each partner is provided with a unique secret key that is shared with the associated advertisers.
The partner's secret key shared with an advertiser is also known as an advertiser key.
If a partner account is associated with multiple advertiser accounts, the partner's secret key allows uploading data for all associated advertisers.
Your decoded secret keys are on the Home page in the platform UI: Advertiser Preferences > Seat Identifiers & Keys.

IMPORTANT: Keep the secret key secure and do not share it.

Signature header authentication

The use signature headers for authentication. To avoid errors, each request must include the following:

The correct signature header type for the endpoint (TtdSignature).
A correct signature header value with an HMACSHA1 base-64 encoding of the body of the JSON post and the secret key. For details on HMACSHA1 encoding, see Microsoft documentation.
- To upload your ID-based user data, use your advertiser secret key.
- To upload your offline conversion data, use the data provider secret key. For assistance, contact your Technical Account Manager.

The following table outlines which signature header to use depending on your data source. Be sure to contact your Technical Account Manager to request the corresponding secret key.

Data Source	Secret Key	Reference
Audience (ID-based) data	Advertiser	Signature header for user data
Offline conversion event data	Provider	Signature header for offline conversions

Signature header for user data

The following table specifies the signature header required for uploading or deleting your ID-based user data.

Header	Value
`TtdSignature`	The HMACSHA1 base-64 encoding of the body of the JSON POST content and the advertiser secret key.

The following is an example of a Postman pre-request script that calculates the value of the TtdSignature header sent in the request.

//hmac : TtdSignature
postman.clearGlobalVariable("hmac");
var secretKey = "ADVERTISER_SECRET_KEY_PLACEHOLDER";
var sha1 = CryptoJS.HmacSHA1(request.data, secretKey);
var base = CryptoJS.enc.Base64.stringify(sha1);
postman.setGlobalVariable("hmac", base);

Signature header for offline conversions

The following table specifies the signature header required for uploading your own offline conversion data.

IMPORTANT: To use the POST /providerapi/offlineconversion endpoint, be sure to obtain a data provider secret key from your Technical Account Manager.

Header	Value
`TtdSignature`	The HMACSHA1 base-64 encoding of the body of the JSON POST content and the data provider secret key.

The following is an example of a Postman pre-request script that calculates the value of the TtdSignature header sent in the request.

//hmac : TtdSignature
postman.clearGlobalVariable("hmac");
var secretKey = "PROVIDER_SECRET_KEY_PLACEHOLDER";
var sha1 = CryptoJS.HmacSHA1(request.data, secretKey);
var base = CryptoJS.enc.Base64.stringify(sha1);
postman.setGlobalVariable("hmac", base);

FAQs

The following is the most commonly asked questions about using the Data API.

Where can I find my secret key?

Your decoded secret keys are on the Home page in the platform UI: Advertiser Preferences > Seat Identifiers & Keys. See also Secret keys.

How do I troubleshoot my signature header authentication?

When you send requests using the signature header, validation applies to check your header type with the value. If your API call fails with a signature header authentication response, check the documentation for the Data API endpoint you're using. There is a table of error information for each endpoint.

Can a data provider upload data on my behalf?

Yes, you can have an external data provider upload your data on your behalf. Contact your Technical Account Manager as you may need to provide your advertiser secret key to the data provider.