Third-party audience data segments and rates

If you have uploaded your third-party data and designed your data taxonomy, you must now organize your data segments into elements to create your taxonomy in The Trade Desk Data Management Platform (DMP).

TIP: If you want to expand an audience segment using cross-device expansion, lookalike modeling, or a combination of both, use the Audience expansion feature.

Before you can create your data elements and assign rates to them, be sure to complete the following tasks:

Initial setup
Design your taxonomy
Depending on the type of data you are integrating, either Third-party audience data integration or Third-party IP address data integration.
Make sure user IDs are assigned correctly to the uploaded data segments. For details, see POST /data/thirdparty.

The following table outlines the steps you need to take to create your third-party data segments and rates. Each step is queued for processing and approval.

IMPORTANT: The listed endpoints are part of Platform APIs that require different authentication than the Data APIs. For details on creating standard and short-lived API tokens, see Foundations.

Create data elements

To create data elements and set up your taxonomy, use the POST /v3/thirdpartydata endpoint from the Platform API suite for each non-root segment in the taxonomy that you have designed.

The following table explains the properties required for creating a data element for either syndicated or custom taxonomy. For a complete reference, see POST /v3/thirdpartydata.

TIP: To facilitate the process of creating data elements for your taxonomy, be sure to have your taxonomy design table for reference.

Display name guidelines

When naming your segments during integration, the DisplayName value must reflect the full path of the segment, which determines both how it appears in the DMP UI and how buyers can find it. For example: In-Market > Travel > Flights > First Class. After your data segments are fully integrated, advertisers will see only the final element in the path—the part after the last greater-than symbol (>). In this example, they would see First Class. For details, see Third-party data taxonomy design.

The value is immutable after it is set. Here are the syntax and content guidelines for creating an effective DisplayName value:

• Use the full path of a segment as a display name.
• Use only greater-than symbols (>) and spaces to separate the path elements.
• Do not include tabs or special characters such as ', ", or ^.
• Use clear, descriptive names and avoid meaningless strings, such as random letters or numbers or placeholders like PROVIDER_NAME or Custom Segment 1234.
• Avoid sensitive terms. Segments containing them may be rejected. For details, see Sensitive categories.

To increase relevance and help advertisers better understand your segments, do the following:

• Ensure the users in your segment match the segment name.
• Build smaller, more targeted segments. For example, instead of having a segment called NY Restaurant Goers, divide it into more specific groups like NY Italian Restaurant Goers and NY Thai Restaurant Goers.

Sensitive categories

The Trade Desk may reject data segments if the DisplayName and Description properties contain terms from sensitive categories. Generally, at this time, the categories The Trade Desk considers sensitive include health conditions, ethnicity, race, religious affiliation, union membership, crime victim status, children's data, and sexual orientation. For details, see Check data change status.

Taxonomy example

The following diagram is a snippet that illustrates the First Class data element from the condensed taxonomy example in Third-party data taxonomy design.

Create data element request

Here's an example of a POST /v3/thirdpartydata request to create the First Class data element from the preceding syndicated taxonomy example.

{
  "ProviderId": "providerXYZ",
  "ProviderElementId": "cj3r",
  "ParentElementId": "ROOT",
  "DisplayName": "In-Market > Travel > Flights > First Class",
  "Buyable": true,
  "Description": "Users currently in market for first-class flights."
}

Here's an example of a POST /v3/thirdpartydata request to create the same data element from a custom taxonomy.

{
  "ProviderId": "providerXYZ",
  "ProviderElementId": "cj3r",
  "ParentElementId": "CUSTOM",
  "DisplayName": "In-Market > Travel > Flights > First Class",
  "Buyable": true,
  "Description": "Users currently in market for first-class flights."
}

After you create all data elements in your taxonomy, assign data rates to buyable segments. Here's what you need to know:

• You can check the approval status two hours after segment creation.
• You can assign rates to data segments that are pending approval.

IMPORTANT: Be sure to assign a rate to your data element within 2 hours of creating it.

Assign rates to data elements

To assign rates to data elements in your taxonomy, use the POST /v3/datarate/batch endpoint from the Platform API suite and update all the buyable segments in the taxonomy as a batch.

IMPORTANT: If a buyable segment does not have a rate or users assigned to it, it will not appear in the DMP.

Rate requirements

Here’s what you need to know about assigning data rates:

• Data rates must be assigned as hybrid rates that use a percentage of media cost with a maximum CPM cap.
• Assign rates only to the buyable segments (data elements with buyable set to true) from your taxonomy unless your taxonomy utilizes rate-inheritance.
• If a buyable segment does not have a rate assigned directly or a rate assigned to its parent, it will not appear in The Trade Desk Data Management Platform (DMP).
• A batch can include a maximum of 5000 rates.
• Be sure to assign each segment to only one brand.

Taxonomy-specific rate requirements

Here's what you need to know about taxonomy-specific rate requirements:

• To specify eligible buyers for your segments, you must to set the rate level based on your taxonomy type: system rate level for syndicated taxonomies and partner or advertiser rate levels for custom taxonomies.
• The integration process is the same for both syndicated and custom taxonomies, except for the RateLevel property values: System for syndicated taxonomies and Partner or Advertiser for custom taxonomies.
• Depending on the rate level, custom taxonomies also require a partner or advertiser ID.

NOTE: You can always update your rates later.

For details, see Third-party data rates.

Data Rates object

The following table explains the DataRates object properties required for creating a data rate batch for either syndicated or custom taxonomy, using your provider ID. For a complete reference, see POST /v3/datarate/batch.

TIP: To facilitate the process of assigning rates, be sure to have a list of all the buyable segments from your taxonomy design table for reference. For details, see Third-party data taxonomy design.

Syndicated taxonomy request

The following is an example of a POST /v3/datarate/batch request to create a rate batch for a syndicated taxonomy.

{
  "ProviderId": "providerXYZ",
  "DataRates": [
    {
      "ProviderElementId": "cj3r",
      "BrandId": "yourBrandID",
      "RateLevel": "System", // Indicates a syndicated taxonomy intended for all buyers.
      "RateType": "Hybrid",
      "PercentOfMediaCostRate": 0.14,
      "CPMRate": {
        "Amount": 2.50,
        "CurrencyCode": "USD"
      }
    },
    {
      "ProviderElementId": "dk4s",
      "BrandId": "yourBrandID", 
      "RateLevel": "System", // Indicates a syndicated taxonomy intended for all buyers.
      "RateType": "Hybrid",
      "PercentOfMediaCostRate": 0.16,
      "CPMRate": {
        "Amount": 3.00,
        "CurrencyCode": "USD"
      }
    }
  ]
}

Custom taxonomy request

The following is an example of a POST /v3/datarate/batch request to create a rate batch for a custom taxonomy.

{
  "ProviderId": "providerXYZ",
  "DataRates": [
    {
      "ProviderElementId": "2130",
      "BrandId": "yourBrand1ID",
      "RateLevel": "Partner", // Indicates a custom taxonomy intended only for the specified partner and their advertisers.
      "PartnerId": "partnerXYZ", // Indicates the partner to which the data element is assigned.
      "RateType": "Hybrid",
      "PercentOfMediaCostRate": 0.14,
      "CPMRate": {
        "Amount": 2.50,
        "CurrencyCode": "USD"
      }
    },
    {
      "ProviderElementId": "2133",
      "BrandId": "yourBrand1ID", 
      "RateLevel": "Partner", // Indicates a custom taxonomy intended only for the specified partner and their advertisers.
      "PartnerId": "partnerXYZ", // Indicates the partner to which the data element is assigned.
      "RateType": "Hybrid",
      "PercentOfMediaCostRate": 0.16,
      "CPMRate": {
        "Amount": 3.00,
        "CurrencyCode": "USD"
      }
    }
  ]
}

TIP: To check the processing of your data rate batch, send a GET /v3/datarate/batch/{batchId} request with the BatchId returned in the response from the POST /v3/datarate/batch request.

For details on the rate processing queue eligibility period, syndicated taxonomy approval status, and other details, see Third-party data rates. See also Manage data elements and rates.

Manage data elements and rates

After you have completed your third-party data integration, you may need to retrieve the taxonomy and data rate details or update them. The following table lists the common management tasks for data elements and rates.

Retrieve brand details

To retrieve a list of brands for your provider ID, for example, to look up a brand ID when assigning rates, use the GET /v3/datarate/brands/{providerId} endpoint.

The following is an example of a GET /v3/datarate/brands/{providerId} body response.

[
  {
    "LogoUrl": "https://s3.amazon.com...",
    "BrandId": "yourBrand1ID",
    "BrandName": "Brand One"
  },
  {
    "LogoUrl": "https://s3.amazon.com...",
    "BrandId": "yourBrand2ID",
    "BrandName": "Brand Two"
  },
  {
    "LogoUrl": "https://s3.amazon.com...",
    "BrandId": "yourBrand3ID",
    "BrandName": "Brand Three"
  }
]

Retrieve taxonomy details

To retrieve a paged list of segments, for example, to view their relationships in the taxonomy or to look up a ProviderElementId value to use as a ParentElementId for a new segment, use the POST /v3/thirdpartydata/query endpoint.

Request example

The following is a POST /v3/thirdpartydata/query request body example of how to retrieve a paged list of segments.

{
  "ProviderId": "providerXYZ",
  "PageStartIndex": 0,
  "PageSize": 50
}

Response example

The following is a POST /v3/thirdpartydata/query response body example with a paged list of segments. Note that the last segment has the sensitive term "peanuts" in the Description property, which led to the denial of segment compliance approval.

{
  "Result": [
    {
      "ThirdPartyDataId": 12345678,
      "TaxonomyComplianceStatus": "Approved", 
      "ProviderId": "providerXYZ",
      "ProviderElementId": "ax7m",
      "ParentElementId": "ROOT",
      "DisplayName": "In-Market > Travel > Car Rentals",
      "Buyable": false,
      "Description": null,
      "AudienceSize": null
    },
    {
      "ThirdPartyDataId": 98745632,
      "TaxonomyComplianceStatus": "Approved", 
      "ProviderId": "providerXYZ",
      "ProviderElementId": "bt9q",
      "ParentElementId": "ROOT",
      "DisplayName": "In Market > Travel > Destinations",
      "Buyable": false,
      "Description": null,
      "AudienceSize": null
    },
    {
      "ThirdPartyDataId": 45632178,
      "TaxonomyComplianceStatus": "Pending",
      "ProviderId": "providerXYZ",
      "ProviderElementId": "cj3r",
      "ParentElementId": "ROOT",
      "DisplayName": "In-Market > Travel > Flights > First Class",
      "Buyable": false,
      "Description": null,
      "AudienceSize": null
    },
     {
      "ThirdPartyDataId": 78932174,
      "TaxonomyComplianceStatus": "Denied", 
      "ProviderId": "providerXYZ",
      "ProviderElementId": "dk4s",
      "ParentElementId": "ROOT",
      "DisplayName": "In-Market > Travel > Flights > Economy Class",
      "Buyable": true,
      "Description": null,
      "AudienceSize": null
    }
  ],
  "ResultCount": 4,
  "TotalFilteredCount": 4,
  "TotalUnfilteredCount": 4
}

Retrieve individual data element details

To retrieve details for a specific segments, for example, to look up the buyable status or a ParentElementId value when creating a sibling segment, use the POST /v3/thirdpartydata/query endpoint.

Request example

The following is a POST /v3/thirdpartydata/query request body example of how to retrieve a specific segment.

{
  "ProviderId": "providerXYZ",
  "ProviderElementId": "el5t",
  "PageStartIndex": 0,
  "PageSize": 1
}

Response example

The following is a POST /v3/thirdpartydata/query response body example with details of a specific segment.

{
  "Result": [
    {
      "ThirdPartyDataId": 78932174,
      "TaxonomyComplianceStatus": "Approved",
      "ProviderId": "providerXYZ",
      "ProviderElementId": "el5t",
      "ParentElementId": "ROOT",
      "DisplayName": "In-Market > Travel > Flights > Business Class",
      "Buyable": true,
      "Description": "Users who have recently looked for web hosting services.",
      "AudienceSize": null
    }
  ],
  "ResultCount": 1,
  "TotalFilteredCount": 1,
  "TotalUnfilteredCount": 1
}

Retrieve data rate details

To retrieve a paged list of all data rates for your provider ID or the rate details for an individual data element, use the POST /v3/datarate/query endpoint.

The following is a POST /v3/datarate/query request body example of how to retrieve a paged list of all data rates in a custom taxonomy.

IMPORTANT: To use this query, you must have a brand ID. To retrieve a list of available brand IDs for your provider ID, use the POST /v3/datarate/brands/{providerId} endpoint.

{
  "BrandId":"brandXYZ",
  "ProviderId": "providerXYZ",
  "RateLevel": "Partner", // Indicates a custom taxonomy intended only for the specified partner and their advertisers.
  "PageStartIndex": 0,
  "PageSize": 10
}

The following is a POST /v3/datarate/query request body example of how to retrieve data rates for a specific segment in a syndicated taxonomy.

{
  "BrandId":"brandXYZ",
  "ProviderId": "providerXYZ",
  "ProviderElementIds": [
    "1113"
  ],
  "RateLevel": "System", // Indicates a syndicated taxonomy intended for all buyers.
  "PageStartIndex": 0,
  "PageSize": 1
}

Remove third-party data segments

NOTE: To remove third-party data segments from a custom taxonomy for a specific partner or advertiser, contact your Technical Account Manager and Data Partnerships lead. Segments will be deleted from all data groups for the specified partners or advertisers. Note that segment removal requires a standard advance client notification of 30 days, with any non-standard notification timelines evaluated on a case-by-case basis.

To remove a third-party data segment from a syndicated or custom taxonomy, complete the following steps.

The following is a PUT /v3/thirdpartydata request body example that shows how to make a segment non-buyable.

{
  "ProviderId": "providerXYZ",
  "ProviderElementId": "fm6u",
  "Buyable": false
}

The following is a POST /data/thirdpartydata request body example that shows how to set the TtlInMinutes for each ID in the segment to 0 to prevent the segment from being used for targeting.

{
   "DataProviderId":"dataproviderABC",
   "Items":[
      {
         "TDID":"1234565c-8bd4-4d93-be5c-a6c22904602c",
         "Data":[
            {
               "Name":"Segment101",
               "TtlInMinutes":0
            }
         ]
      },
      {
         "TDID":"a1b2c3ea-338b-4230-a333-363db5ae20ax",
         "Data":[
            {
               "Name":"Segment101",
               "TtlInMinutes":0
            }
         ]
      }
   ]
}

Data rate approval criteria

After a data rate batch is submitted, the The Trade Desk Data Partnerships team reviews it for processing. The following table describes various rate types and their approval criteria.

NOTE: When the CPM or rate set exceeds the minimum requirements, approval is granted automatically, except in the case of rate changes for syndicated taxonomies.

If you have questions about rate approvals, contact your Data Partnerships Representative.

Check data change status

Two hours after segment creation, use the POST /v3/thirdpartydata/query endpoint to check its taxonomy compliance status. This endpoint retrieves a list of data elements, each with a TaxonomyComplianceStatus property indicating its compliance status. For details, see Retrieve taxonomy details.

The following table describes each value in the TaxonomyComplianceStatus property.

NOTE: You can also use the GET /v3/thirdpartydata/status/{providerId}/{providerElementId} endpoint to check the compliance status of an individual segment.

If the approval status is set to Denied, do the following:

1. If the data element contains sensitive terms but otherwise its data complies with your contract, re-word the segment display name and description to exclude sensitive terms. If you are an onboarder, coordinate with your brands.
2. Use the POST /data/thirdparty endpoint to create a new segment with updated taxonomy and IDs in the Name field, then assign the rates. This replaces the denied segment.

IMPORTANT: You cannot edit the denied segment for approval. You must submit a new segment, along with new users and rates.

Next steps

If you want to expand an audience segment using cross-device expansion, lookalike modeling, or a combination of both, use the Audience expansion feature.

FAQs

The following is a list of commonly asked questions about third-party data integrations.

After I create my data elements, when should I check their status?

While you can verify the status of your data element at any time using the POST /v3/thirdpartydata/query or GET /v3/thirdpartydata/status/{providerId}/{providerElementId} endpoint, the status will be updated to either Approved or Denied around two hours after submission.

In some cases, if a data element requires additional vetting, the status may remain in Pending status, and your segment will not appear in the DMP until the necessary processing is complete.

Can I assign rates to data segments before they are approved?

Yes. You can assign rates to data segments that are pending approval.

What if I have the fast pass for data rate processing and want to use my segment immediately after creation?

With fast pass, your data rates are processed immediately, bypassing the processing window, and made available in the DMP within six hours. Segment creation takes about two hours for approval or rejection, which is within the time needed for rates to appear in the DMP.

When does a third-party data segment become visible in the DMP?

A third-party data segment becomes visible in the DMP when it meets the following conditions:

• The segment has an Approved or NotInQueue taxonomy compliance status.
• The segment has more than 1000 received unique devices/browsers or more than 10 active device/browsers. For details, see Unique ID counting methodologies.
• The Buyable property of the segment is set to true. For details, see Third-party data taxonomy design.
• The segment is assigned a rate specifying which buyers can see the segment.

Can I change a data element's parent element after it is created?

No, you can’t do it using the API. If you would like to change a data element's parent element, contact your Technical Account Manager.

How can I check the current uniques for one of my segments?

To check the current uniques, contact your Technical Account Manager for assistance.

How do data partners link segments from the Data APIs to the Third-Party Data Taxonomy platform APIs?

Through the unique ID that you assign to the segment when designing your taxonomy. This element ID is used as a value in the following fields:

• The Name field in the POST/data/thirdparty Data API used to upload third-party data.
• The ProviderElementId in the POST /v3/thirdpartydata endpoint from the Platform API suite, which is used to create non-root segments in the taxonomy.