Standard contextual categories

NOTE: This guide is intended for third-party contextual providers who plan to upload their categories and make them available to all buyers (partners) in the platform. To make your data available only to select buyers, see Custom contextual categories.

Standard contextual categories are global categories that you create and upload to The Trade Desk platform for all partners to query and apply to bid lists. These are predefined, "off-the-shelf" targeting categories that can be used by any advertiser at scale. They include arts, entertainment, sports, and many other categories and may be organized hierarchically.

Prerequisites

IMPORTANT: To create and upload categories to the platform, you must first set up your data element pricing and have it approved by The Trade Desk Data Partnerships team. If you have not completed these steps, be sure to follow the instructions in Third-party contextual data integration before you proceed.

Here's what you need to get started with creating and uploading your standard categories:

Your third-party data provider ID, provided during the initial setup.
Your ID and name for each category you want to upload.

Category ID requirements

When you include category IDs in the response, make sure they meet the following requirements:

• Included in your contextual data taxonomy
• Lowercase letters
• The category prefix you received from your Technical Account Manager

Create a standard contextual category

Here's what you need to know about creating standard categories:

• The Contextual standard category endpoints use the Platform API authentication tokens.
• If you create, rename, archive, or restore a standard category, an approval process is automatically triggered. You must get your changes approved by The Trade Desk Data Partnerships team before they go live in The Trade Desk platform.

To create your standard contextual category to The Trade Desk platform, complete the following task.

Here's an example of a POST /v3/contextualdata/{providerId}/standardcategory request.

IMPORTANT: If you have multiple category types, be sure to specify the ContextualCategorySourceType value. You cannot change the CategoryBidListType value after you create the category.

{
  "CategoryId": "xyz098",
  "CategoryName": "Car Rentals",
  "ContextualCategorySourceType": "GrapeshotContextualCategory",
  "CategoryBidListType": "Both",
  "ParentId": "travel_123"
}

A successful response returns the category information. For example:

{
  "Id": "xyz098",
  "Name": "Car Rentals",
  "Path": "Travel > Car Rentals",
  "ParentId": "travel_123",
  "CategoryBidListType": "Both"
}

Next steps

After you have uploaded your categories, assign them to your data elements for pricing. For details, see Third-party contextual data integration.

Management tasks for standard contextual categories

The following table lists all tasks and corresponding endpoints relating to the management of standard contextual categories owned by third-party data providers.

Update a standard contextual category

To update a standard category, in a PUT /v3/contextualdata/{providerId}/standardcategory request, specify the ID of the standard category you want to update.

{
  "CategoryId": "xyz098",
  "CategoryName": "Auto Rentals",
  "ParentId": "travel_123"
}

A successful response returns the category information. For example:

{
  "Id": "xyz098",
  "Name": "Auto Rentals",
  "ParentId": "travel_123",
  "Path": "Travel > Auto Rentals"
}

Retrieve all standard contextual categories owned by a third-party data provider

To retrieve a list of a data provider's standard contextual categories, in a POST /v3/contextualdata/{providerId}/standardcategory/query call, specify your provider ID as a path parameter. The following example shows how to use a search token to filter results by category name.

{
  "SearchToken": "Auto Rentals"
}

A successful response returns a list of partner IDs to which the standard category is assigned. For example:

{
  "PagingToken": "sfsf55sdf%",
  "PageSize": 1,
  "Categories": [
    {
      "Id": "xyz098",
      "Name": "Flights",
      "ParentId": "travel_123",
      "Path": "Travel > Auto Rentals"
    }
  ]
}

Error status and messages

FAQs

The following is a list of commonly asked questions about standard contextual categories for third-party data providers.

Can I restore a category after I delete it?

Yes, archiving a contextual category is a soft delete. To restore a contextual category, use the PUT /v3/contextualdata/{providerId}/standardcategory/{standardCategoryId}/unarchive endpoint.

Can I change a standard category to a custom category?

No. You must create a new custom category. For details, see Third-party data providers' custom contextual categories.

Can I edit a category after I create it?

No. To change a category, you must delete the current category create a new category with the changes you want to make.

Can the keywords in my contextual characters contain special characters?

No. The Trade Desk does not support special characters in key words for contextual data.

Can I specify how I want advertisers to use my categories?

Yes, in a POST /v3/contextualdata/{providerId}/standardcategory call, set the CategoryBidListType value to either Block, Target, or Both.