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.

For details on specific workflows, see Getting started with data integrations and Data integration, ID deletion and opt-out.

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 third-party data servers to which you can upload your data:

Location	Base URL	Notes
Global	`https://bulk-data.adsrvr.org`	This location is actually on the US East Coast, but we replicate to other data centers globally.
China	`https://data-cn2.adsrvr.cn`	This location 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:

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

Signature header authentication for commerce data (legacy)

NOTE: To authenticate to the Data API, you must use token authentication. Secret keys and signature headers are legacy authentication methods.

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.

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);

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.

How do I authenticate for uploading real-time conversion event data?

The POST /track/realtimeconversion endpoint does not require authentication.