Custom contextual categories

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

Custom contextual categories are lists of keywords and phrases that you can build with customizations based on The Trade Desk users' requirements. These categories have a flat structure with no hierarchical, parent-child relationships.

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 uploading your custom categories:

Your data provider ID, provided during the initial setup.
Your ID and name for each category you want to upload.
The Trade Desk partner ID of each partner to whom you want to assign your custom contextual categories.

Upload custom contextual categories

To upload your custom contextual category to The Trade Desk platform, complete the following steps.

IMPORTANT: The Contextual custom category endpoints use the Platform API authentication.

Create a custom contextual category

To create a custom contextual category in The Trade Desk platform, in a the POST /v3/contextualdata/{providerId}/customcategory request, specify the name and ID of the custom contextual category.

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": "gs_abc123",
  "CategoryName": "Fitness",
  "CategoryBidListType": "Both",
  "ContextualCategorySourceType": "GrapeshotContextualCategory"
}

A successful response returns the category information. For example:

{
  "Id": "gs_abc123",
  "Name": "Fitness",
  "ParentId": null,
  "Path": "Fitness",
  "CategoryBidListType": "Both"
}

NOTE: The ParentId value always returns null for custom categories because they are not organized hierarchical.

Assign a custom contextual category to a buyers

To assign a category to a partner in The Trade Desk platform, just include your provider ID, your category ID, and The Trade Desk partner ID as path parameters in a PUT /v3/contextualdata/{providerId}/customcategory/{customCategoryId}/partner/{partnerId}/assign call.

TIP: To retrieve the custom contextual category to which you want to assign a partner, use the GET /v3/contextualdata/{providerId}/customcategory/{customCategoryId} endpoint.

Next steps

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

After you have uploaded and selected buyers for your categories, you must assign the categories to your data elements (charges) for pricing. For details, see Third-party contextual data integration.

Management tasks for custom contextual categories

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

Update a custom contextual category

To update the name of a custom category, in a PUT /v3/contextualdata/{providerId}/customcategory call, specify the ID of the custom category you want to update and the new name for the category.

{
  "CategoryId": "gs_abc123",
  "CategoryName": "CrossFit"
}

A successful response returns the category information with the new name. For example:

{
  "Id": "gs_abc123",
  "Name": "CrossFit",
  "ParentId": null,
  "Path": "CrossFit"
}

Retrieve all partners assigned to a custom contextual category

To retrieve a list of partners to which a custom contextual category is assigned, in a POST /v3/contextualdata/{providerId}/customcategory/category/query/partners request, specify the ID of the category in the body.

{
  "CategoryId": "gs_abc123"
}

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

{
  "PagingToken": "dftf56sdf%",
  "PageSize": 2,
  "PartnerIds": [
    "partnerID1",
    "partnerID2"
  ]
}

Error status and messages

The following table provides a list of common errors and their respective error status.

FAQs

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

What happens after I unassign a category from a partner?

The Trade Desk partner can no longer query or apply the category to any of their ad group bid lists. Any of the partner's existing ad group bid lists with the category are still valid.

What happens if I delete a category that is assigned to a partner?

The Trade Desk partner can no longer query or apply the category to any of their ad group bid lists. Any of the partner's existing ad group bid lists with the category are still valid.

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}/customcategory/{customCategoryId}/unarchive endpoint.

Can I change a custom category to a standard category?

No. You must create a new standard category. For details, see Standard 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.

How do can advertisers find the custom categories I assign them?

After you assign a partner to your custom category and finish integrating your contextual data, the partner can access your category in the platform UI.

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}/customcategory call, set the CategoryBidListType value to either Block, Target, or Both.