Data API SDK

NOTE: This guide describes one method for uploading offline conversion events. For all available methods, see Upload offline conversion events. If you're uploading event data as part of the product catalog integration workflow, first complete Step 2: Upload product catalog data.

The Data API SDK enables you to onboard conversion or segment data to The Trade Desk or to manage optouts and deletions. It is a Python SDK that simplifies sending advertising data to The Trade Desk DSP. It can substantially reduce the time, effort, and complexity of authoring your integration.

This SDK solution encapsulates complex functionality such as retries, external API handshake, and error handling. It's an easy alternative to calling the various Data API endpoints directly.

IMPORTANT: Although this is a simplified solution, using it requires writing code and managing credentials such as secrets.

Your specific implementation of the SDK might require ongoing operational work.

For details about the underlying API, see Data API.

Key resources

Unlike other offerings from The Trade Desk that offer a higher level of assistance from The Trade Desk personnel, this solution is supported primarily by written documentation on the Python Package Index (PyPI) site and notes on the OpenTTD portal.

The following table provides information about additional key resources for getting started with The Trade Desk Data API SDK.

Resource	Link
Project page on PyPI site	ttd-data project
GitHub repository	ttd-data-python

Key capabilities

The Data API SDK supports management of the following functions and types of data:

First-party targeting data for advertisers and onboarders
Third-party targeting data for data providers and commerce partners
Offline conversion data for advertisers, providers, and commerce partners
Deletion/opt-out workflows for managing advertising identifiers
Third-party data taxonomy (creating and querying data elements) for data providers
Third-party data rate management (creating and querying data rate batches) for data providers
Automatic UID2 generation from hashed or unhashed email addresses or phone numbers (Email, HashedEmail, Phone, HashedPhone)

NOTE: The Data API SDK converts the data that you provide to UID2s before sending it to The Trade Desk, using the UID2 Operator that you specify in the UID2Config object. If you are using an EUID Operator, the SDK can generate EUIDs. It never sends raw emails or phone numbers to The Trade Desk: it sends the UID2s or EUIDs.

Authentication

Here's what you need to know about authentication for this SDK:

The SDK uses API token authentication. This is the only valid method of authentication for the SDK.
The token is required when you create an API context alongside the client; the same token is then automatically included with every request.

Deployment

The SDK is distributed as a Python package (ttd-data) through PyPI. The deployed package includes the following:

A library of capabilities of the base implementation from The Trade Desk, managing fundamental aspects of sending audience and event data to The Trade Desk DSP.
SDK usage examples that you can personalize for your specific implementation.

To install, run this command:

pip install ttd-data

When installation is complete, you can use the SDK to send audience and conversion data to The Trade Desk Data API or to manage deletions and optouts. For details, refer to the project page on the PyPI site or the GitHub README file: see Key resources. For examples, see SDK Example Usage.

Support

Full documentation is available in the package README on PyPI. It covers installation, available endpoints, schema requirements, error handling, and advanced configuration such as custom HTTP client, server URL overrides, and backfill runs.

If you encounter any issues, or have a feature request, let us know through the Issues link in the GitHub repository.

FAQs

The following is a list of commonly asked questions about the Data API SDK.

How do I get an API token?

The SDK uses the same enablement mechanics as a Data API integration from The Trade Desk. For details, see API token authentication.

Does the SDK support header-based authentication?

No. The only valid authentication for this SDK is API token authentication.

What Python versions are supported?

The latest information on supported Python versions is on the PyPI project page: See ttd-data project and look in the left sidebar, under the Meta heading.

How does the SDK handle retries and failures?

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it falls back to the default retry strategy provided by the underlying Data API. However, you can override the default retry strategy on a per-operation basis or across the entire SDK. For details, see Retries in the GitHub README.md file.

For information about managing failures, see Error Handling.

Can I use the SDK for backfill / large historical uploads?

Yes, you can; however the cap or quota limits are the same as they are for the Data API. Using the Data API SDK is an easier way to integrate, but doesn't increase your data quota.

For data limits for a specific endpoint, refer to the API documentation for that endpoint on OpenTTD. For example, for offline conversions, see POST /providerapi/offlineconversion.

Does the SDK send raw emails or phone numbers to The Trade Desk?

No, the SDK never sends raw emails or phone numbers. It converts the data that you provide to UID2s or EUIDs before sending it to The Trade Desk, using the UID2 Operator that you specify in the UID2Config object, and then it sends the UID2s or EUIDs.

Is there a sandbox or test environment?

No. There is currently no sandbox or test environment for the Data API SDK.

I already have an integration workflow build around the API. Can I switch to using the SDK?

Yes. This is a self-serve solution. You can always switch to the SDK. The only requirement is that you must create your own platform authentication token. For details, see API token authentication.

Next steps

If you uploaded event data only for measurement, your integration is complete.

If you uploaded event data as part of a product catalog integration, the next step is to activate the data through your product catalog. To share access, continue to Step 4. Manage product catalog access. After an advertiser has access to the catalog, they can create product lists to build audiences and measure sales performance.