Third-party contextual data integration

After the Data Partnerships team approves your contextual data taxonomy, typically during week three of the integration timeline, you can now onboard your contextual categories and sell them to advertisers in The Trade Desk platform. To do this, you must create the data elements in your taxonomy and assign prices to them. This enables advertisers in the platform to view the name, price, and ID of your categories, which they need to use your categories for targeting. After you create your data elements, you must assign your pricing, receive approval, then upload your contextual categories to the platform.

Access and authentication

Here's what you need to know about accessing and authenticating with The Trade Desk API:

Some endpoints and documentation might require access permissions. If you can't access any information, be sure to contact your Technical Account Manager.
All Contextual Data, Rate, and other platform endpoints use the API token authentication and do not require secret keys.

The following sections provide a list of key terms and data IDs to help you better understand and navigate the process, and to avoid confusion. The workflow section outlines all the steps you need to follow and includes links to relevant endpoints and guides, ensuring you have the resources to successfully onboard your data.

Term definitions

The Contextual Data APIs and user documentation might use certain terms, such as "data elements" and "charges," interchangeably. The following table defines the key terms you might encounter when onboarding or integrating your data. See also Glossary.

Term	Definition
Contextual Category	This term refers to categories that are lists of keywords and phrases that are matched to the content of webpages and apps.
Category Charge	This API term refers to the mapping of a contextual category to a data element.
Charge	This is another term for "data element" used in the context of pricing your contextual categories. You create charges to organize and assign rates to your contextual categories in the platform.
Custom category	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. You can assign these categories to specific buyers in the platform.
Data element	A data element is a group of contextual categories with the same rate in The Trade Desk contextual marketplace. It enables advertisers to view and access the name and pricing information for a set of contextual categories.
Standard category	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. These categories are created in accordance with IAB guidelines and include arts, entertainment, sports, and so on, and may be organized hierarchically. These categories are available to all buyers in the platform.
Tactic	The pre-bid tactic determines how advertisers discover your categories in The Trade Desk platform and indicates how advertisers can use your data for pre-bid targeting and blocking.

Onboarding workflow

NOTE: You can make your data available to all buyers in the platform or only to certain buyers that you specify. The category type that you choose (standard or custom) determines which buyers can use your data to build their audiences.

The following table outlines the onboarding process step by step with links to the relevant guides for each step.

Step		Description	Endpoint or Further Reference	Notes
1		Create your contextual data taxonomy and submit it to The Trade Desk Data Partnerships team for approval.	Contextual data taxonomy design	You must get your rates approved before you can onboard your data.
2		Implement your taxonomy in the platform by creating your data elements and rates.	Contextual category pricing and rates	Be sure to have your brand ID. Your charge group ID is assigned automatically and can be retrieved using the query endpoint before creating data elements.
3		Decide which categories you want to share with all buyers, and which ones you want to share with only specific buyers, and complete either of the following steps, respectively.	N/A	None.
	a	If you want to share your data with all buyers in the platform, upload your contextual categories as standard categories.	Standard contextual categories	None.
	b	If you want to share your data only with selected buyers in the platform, upload your contextual categories as custom categories and assign them to the partners of your choice.	Custom contextual categories	None.
4		Assign your categories to your data elements for pricing.	POST /v3/contextualdata/{providerId}/categorycharge	None.

After this process is complete, advertisers can purchase your contextual categories and use them for targeting purposes in their campaigns.

Data IDs

The following table lists the different IDs that are required or returned when you are onboarding and managing your contextual categories in the platform.

ID Property	Description	Value Origin or Location
`ProviderId`	Identifies your provider account in the platform.	This ID was assigned to you and included in the information you received from your Technical Account Manager. If you don’t know your provider ID, contact your Technical Account Manager.
`BrandId`	Identifies the brand that you manage. This ID is used for category pricing.	This ID is provided during your onboarding process. For details, see Getting started. To look up your brands, use the GET /v3/datarate/brands/{providerId} endpoint.
`ChargeGroupId`	Identifies the charge group assigned to you in the platform. This ID is used for creating data elements.	For a list of charge group IDs available to you, use the POST /v3/contextualdata/{providerId}/chargegroup/query endpoint.
`ProviderElementId`	The platform ID that advertisers need to use your data.	This ID is returned after you create a data element. For a list of data elements available to you, use the POST /v3/contextualdata/{providerId}/charge/query endpoint.
`ParentElementId`	Identifies the type of categories assigned to a data element: custom or standard. There are two parent element IDs automatically created for you, one for standard data elements and another for custom data elements.	For a list of parent element IDs, use the GET /v3/contextualdata/{providerId}/parentelementid endpoint.
`CategoryId`	Identifies a contextual category. You specify this ID when creating a category.	For a list of category IDs that you created, use the GET /v3/contextualdata/{providerId}/parentelementid endpoint.