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:

1. Log in with your The Trade Desk account credentials.
2. Navigate directly to the OpenTTD Access Management app.
3. Click Generate Token / Key. The Generate API Token dialog appears.
4. 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.
5. In the Application field, select Platform API.
6. Select the token lifetime based on your key rotation strategy and integration needs.
7. Click Save. A confirmation message appears with an API token.
8. Copy the displayed API token, save it to your secrets management system for future reference, and then close the message.
9. 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

Depending on whether you're uploading first-party data on behalf of an advertiser or third-party data, you must select the appropriate data center for your requests.

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

Third-party data servers

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

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

• To find out the best location to upload your data, contact your Technical Account Manager.
• There are cases where some providers use different data centers or base URLs that are not on this list, depending on their individual business needs.
• The following data providers might need to have unique base URLs set up:
  • Large data providers
  • Data providers located in China
  • Data providers that have latency requirements

First-party data servers

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

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

Whether you are an external first-party data or third-party data provider, you must use a secret key in all requests for uploading data. When you send data, the included secret key is validated against the secret key the platform has on file for the advertiser or provider ID that you specify in the request. Here's what you need to know about secret keys:

• External and third-party data providers must obtain their decoded secret keys from their Technical Account Managers.
• Advertisers have decoded secret keys stored on the Home page in the platform UI: Advertiser Preferences > Seat Identifiers & 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.

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

Signature header authentication

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

• The correct signature header type for the endpoint (TtdSignature).
• The 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.

IMPORTANT: External first-party data providers must use two headers, TtdSignature and TtdSignature-dp. For details, see Signature headers for external first-party data providers.

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.

Signature header for third-party data

The following table specifies the signature header required for uploading or deleting your data.

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 = "DATA_PROVIDER_SECRET_KEY_PLACEHOLDER";
var sha1 = CryptoJS.HmacSHA1(request.data, secretKey);
var base = CryptoJS.enc.Base64.stringify(sha1);
postman.setGlobalVariable("hmac", base);

Signature headers for external first-party data providers

As an external provider, you need to use the following two headers encoded with the two secret keys, provider and advertiser.

The following is an example of a Postman pre-request script that uses the two signatures:

//hmac : TtdSignature
//hmac2 : TtdSignature-dp
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);

postman.clearGlobalVariable("hmac2");
var secretKey2 = "DATA_PROVIDER_SECRET_KEY_PLACEHOLDER";
var sha1 = CryptoJS.HmacSHA1(request.data, secretKey2);
var base2 = CryptoJS.enc.Base64.stringify(sha1);
postman.setGlobalVariable("hmac2", base2);

FAQs

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

Where can I find my secret key?

You must contact your Technical Account Manager. 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.