Getting started for contextual data providers

NOTE: This guide is intended for third-party providers who are interested in selling their pre-bid inventory metadata to The Trade Desk advertisers. For ID-based data, see Getting started for audience data providers.

The Trade Desk contextual targeting enables advertisers to deliver relevant ads by matching identified categories, keywords, or phrases with the content of a website. By using this solution, advertisers can reach customers at the right moment by matching ads with the content being consumed.

As a third-party data provider, you can surface your contextual data categories in The Trade Desk platform and make them available for all partners and advertisers to query and apply to their ad group bid lists.

Integration timeline

The integration process takes about four weeks. During this time, you collaborate with your Data Partnerships Manager and Technical Account Manager at The Trade Desk to test your API capabilities and onboard your contextual data. Here's what you need to know:

• The timeline can vary depending on your API capabilities and the level of collaboration between teams.
• You must have an API that meets the required capabilities available by week two. For details, see API requirements.

The following table lists the key milestones of the integration timeline.

Get started

To prepare for the contextual integration process, complete the following steps:

1. Make sure your API meets The Trade Desk requirements.
2. Set up your API to do the following:
   • Receive multiple API calls from The Trade Desk requesting contextual information about multiple URLs and app IDs.
   • Respond to the API calls with information about the categories that you want to assign to each URL in the request.
3. Contact the Data Partnerships team and do the following:
   Confirm your API capabilities.
   Sign all required paperwork.
   Provide all required information.
   
4. Work with your Data Partnerships Manager to decide which pre-bid tactics apply to your contextual category data. These tactics determine how advertisers discover your categories in The Trade Desk platform.

API requirements

The API that you use to send contextual category data must meet the following requirements:

Multiple API endpoints for different regions such as US East, US West, APAC, EMEA, and so on.
Receive more than 50,000 API calls per second worldwide (global QPS).
Respond to requests within 200 ms or less.
Receive requests in The Trade Desk templatized format.

After your Data Partnerships Manager evaluates and confirms that you can meet these requirements, The Trade Desk will add you to our contextual roadmap.

TIP: If you currently cannot meet the requirements but anticipate that you will be able to in the future, contact your Data Partnerships Manager.

Receive API calls from The Trade Desk

After your API meets The Trade Desk requirements, set up your API to receive calls from The Trade Desk requesting contextual information about a URL. Each request uses a templatized format that includes the following path parameter values.

The following examples show how The Trade Desk sends requests for different inventory types.

Web URL request example

Here's an API call example of how The Trade Desk requests contextual information with two path parameters: one that has an inventory signal (URL, app ID, or content metadata) and another to indicate whether the signal is an app ID.

GET https://provider-contextual.com/contextual?URL=https://www.invalidrandomdomain.com/live-cricket-score&InApp=false

CTV inventory request with additional parameters

For CTV and audio inventory, The Trade Desk includes additional parameters such as the contentId and contentType fields, along with optional metadata fields such as title, series, genre, and so on. Here's an example CTV inventory request:

GET https://provider-contextual.com/contextual?URL=https://www.invalidrandomdomain.com/live-cricket-score&InApp=false&contentId=956487&title=TITLE_OF_TV_SHOW_PLACEHOLDER&episode=EPISODE_NAME_PLACEHOLDER&contentType=ConnectedTv

The CTV inventory example includes the following placeholder values:

• TITLE_OF_TV_SHOW_PLACEHOLDER: The show title.
• EPISODE_NAME_PLACEHOLDER: The episode name.
• 956487: An example content ID.

In-app URL request

Here's an example in-app URL request:

GET https://provider-contextual.com/contextual?URL=com.example.random&InApp=true

NOTE: Each request from The Trade Desk uses a fixed templatized format and cannot be altered.

Respond to API calls from The Trade Desk

For the response, you must include a list of category IDs that you plan to assign to the URL in the request, the time to live in seconds (TTL), and the status of your contextual data. The response must be in the following format.

{
    "categories": [
        "abc-12345",
        "abc-9876",
        "abc-6789"
    ],
    "status": 1,
    "ttlInSeconds": 3600
}

The following table lists the object properties that you must include in the response.

Status enum values

The following table lists the status values you need to set in the response.

Time to live values

The following table lists the minimum, maximum, and default ttlInSeconds values for each status.

If your API meets our requirements, contact your Data Partnerships Manager and provide the required information.

Information you need to provide

After you set up an API that meets our requirements, contact your Data Partnerships Manager and provide the following information.

Information you need to receive

After your account is set up, your Technical Account Manager will provide you with the following information.

Next steps

Before you continue, be sure to do the following:

• If you haven't yet received the required information from your Technical Account Manager, contact them before proceeding.
• Complete your contextual data taxonomy design and have it approved by your Data Partnerships Manager and Technical Account Manager.

After you have the required information and your taxonomy is approved, continue to Third-party contextual data integration.

FAQs

The following is a list of commonly asked questions about the initial setup for contextual data providers.

Can The Trade Desk gradually send requests by region or data center?

No, all requests are sent during the second or third week of the integration timeline. If needed, you can indicate that a request is pending and has not been processed or ignored to indicate that you will not process the request. To do this, set the appropriate status value.

Where should I set up my API endpoints?

Set up one endpoint for each of your own data centers per region (US East, US West, APAC, EMEA).

If needed, you can also set up one global endpoint for all data center regions (this depends on the IP-Geo service that you use).

Can I set up one global endpoint to receive all traffic?

You can, but use it only as a temporary solution while you set up your endpoints for each data center region.

When should I be ready to send responses with category IDs to The Trade Desk?

Be sure to have your responses in the required format, which includes category IDs, ready before the start of week one on the integration timeline.

What happens if I don't provide a TTL value for my response?

The Trade Desk defaults to the following values in seconds.

For details, see Time to live in seconds.

What additional metadata or parameters can The Trade Desk include in requests for CTV and audio inventory?

In addition to the contentId and contentType parameters, requests for both CTV and audio inventory might also include any of the following parameters:

• title
• series
• genre
• rating
• season
• episode
• channel
• livestream
• language
• qagMediaRating

What's the difference between a request for audio inventory and a request for CTV inventory?

The type of inventory for the request is indicated by the contentType path parameter. For example, audio inventory requests have contentType set to audio.