Default bid lists

Default bid lists are intended for grouping bid lists that are common across most campaigns for a specific advertiser and/or across most ad groups under a campaign. Thus, instead of setting up bid lists for individual campaigns and ad groups, you can save time and effort by creating default bid lists that are housed at the advertiser or campaign level. The advertiser default lists can be propagated to any new campaigns created for the advertiser as needed and subsequently applied to any ad groups within those campaigns. The campaign default bid lists, which allow a wider variety of dimensions, can be applied to new ad groups under each campaign as needed. Once an advertiser or campaign default bid list is applied to an ad group, it is automatically enabled for bidding.

Standard vs. default bid lists

Default bid lists are a subset of standard bid lists, which allows more user control, efficiency, and granularity in bid list management as well as complete parity and visibility in the UI. The following table provides a high-level comparison. For details on standard bid lists, see Bid lists.

Allowed dimensions in default bid lists

• Default bid lists can be only single-dimensional. Multi-dimensional bid lists are currently not allowed.
• Some dimensions may require permissions. If needed, please contact your Account Manager for help.
• At the campaign level, default bid lists can include any dimensions, except HasVideoPlayerSizeId.
• At the advertiser level, default bid lists can include only the following dimensions.

What you need to know

Here’s what you need to keep in mind when working with default bid lists. They:

• Are optional and single-dimensional. You can associate bid lists with campaigns and ad groups on an individual basis as explained in Bid lists.
• Can be only of type TargetList or BlockList (specified in BidAdjustmentType). You cannot add Optimized bid lists, such as Volume Control bid lists, as default ones.
• Can be defined only at the advertiser or campaign level. Advertiser default bid lists have a limited number of dimensions that can be used.
• If included, get propagated sequentially to the descendants by following the bid list inheritance rules. For details, see Bid lists.
  For example, the advertiser’s default bid lists cannot be applied directly to ad groups without first including them in the advertiser’s campaigns.
• Will not be automatically applied to the advertiser’s existing campaigns or their existing ad groups.
• May be included only in the advertiser’s new campaigns, by setting the IncludeDefaultsFromAdvertiser parameter to true in the POST/campaign request. The applied default bid lists are automatically added to the DefaultBidLists array.
• May be included only in new ad groups, using the IncludeDefaultsFromCampaign parameter to true in the POST/adgroup request. The applied default bid lists are automatically added to the AssociatedBidLists array with the following settings, which you can update as needed:
  • The IsEnabled parameter set to true.
  • The IsDefaultForDimension parameter set to false.
• If the same bid list is already applied to the campaign or ad group, it will be included only once.
• When included, the applied default bid lists in the DefaultBidLists array for campaigns and the AssociatedBidLists array for ad groups can be subsequently retrieved using the respective GET requests and updated using the respective PUT requests and as needed, but no new default bid lists can be included from the parent advertiser or campaign.

FAQs

The following table provides a matrix of answers to some default bid list FAQs about each entity involved.

Endpoints

The following table lists the endpoints for creating, updating, applying, and retrieving default bid lists.

IMPORTANT: Since arrays in PUT requests replace the current ones instead of adding to them, if you want to add bid lists to any current arrays, make sure to retrieve them with the respective GET requests first and then include the current and new values in respective PUT requests with any other appropriate changes.

See also Request examples.

Apply advertiser's default bid lists

The following table outlines the process of creating a set of default bid lists for an existing advertiser and including them as default bid lists in a new campaign and a new ad group for that campaign.

Update campaign default bid lists

The following table outlines the process of creating a set of default bid lists for an existing campaign and including them as associated bid lists in a new ad group for that campaign. The sections that follow provide code examples for each request.

Request examples

The following are code snippets of request examples illustrating the steps in the Applying advertiser's default bid lists and Updating campaign default bid lists procedures.

• Create bid lists
• Add bid lists as defaults
• Include advertiser's default bid lists in a new campaign
• Retrieve campaign information
• Add default bid lists to an existing campaign
• Include campaign default bid lists in a new ad group

Create default bid lists

To create default bid lists, set the BidListAdjustmentType property to TargetList or BlockList. The following is a POST /v3/bidlist request body example with that property set to TargetList.

{
    "Name": "DEFAULT_BID_LIST_NAME_PLACEHOLDER",
    "BidListAdjustmentType": "TargetList",
    "BidLines": [
        // Include the dimensions that you want applied to all campaigns.
    ],
    "BidListOwner": "Advertiser",
    "BidListOwnerId": "abcd1234"
    // Include other required fields.
}

Add bid lists as defaults

The following code snippet can be included in the respective POST and PUT advertiser or campaign requests.

IMPORTANT: Since arrays in PUT requests replace the current ones instead of adding to them, if you want to add bid lists to any current arrays, make sure to retrieve them with the respective GET requests first and then include the current and new values in respective PUT requests with any other appropriate changes.

{
    "DefaultBidLists": [
        {
          "BidListId": "efgh5678"
        },
        {
          "BidListId": "ijkl9012"
        }
    ]
    // Include other required fields.
}

Include advertiser's default bid lists in a new campaign

To include an advertiser's default bid lists in a new campaign, set the IncludeDefaultsFromAdvertiser property to true. The applied default bid lists are automatically added to the DefaultBidLists array. The following is a POST /v3/campaign request body example with that property set to true.

TIP: If you want to include other bid lists to the campaign in addition to the advertiser’s default bid lists, include the DefaultBidLists array with the IDs of the additional bid lists in the request.

{
    "AdvertiserId": "abcd1234",
    "CampaignName": "CAMPAIGN_NAME_PLACEHOLDER",
    "CampaignConversionReportingColumns":[
        {
            "TrackingTagId": "12345678ab",
            "ReportingColumnId": 1
        }
    ],
    "IncludeDefaultsFromAdvertiser": true
    // Include other required fields.
}

Retrieve campaign information

To retrieve campaign information such as associated default bid lists, use the GET /v3/campaign/{campaignId} endpoint. The following request example uses an authorization token, which is required by The Trade Desk API to authorize the request.

curl --location --request GET 'https://api.thetradedesk.com/v3/campaign/t0ncimu' \
--header 'Content-Type: application/json' \
--header 'TTD-Auth: yourauthtoken'

Add default bid lists to an existing campaign

To add default bid lists to an existing campaign, use the PUT /v3/campaign endpoint. The following is an example of a request to update a campaign by adding two default bid lists.

IMPORTANT: Since arrays in PUT requests replace the current ones instead of adding to them, if you want to add bid lists to any current arrays, make sure to retrieve them with the respective GET requests first and then include the current and new values in respective PUT requests with any other appropriate changes.

{
    "AdvertiserId": "abcd1234",
    "CampaignName": "CAMPAIGN_NAME_PLACEHOLDER",
    "CampaignConversionReportingColumns":[
        {
            "TrackingTagId": "12345678ab",
            "ReportingColumnId": 1
        }
    ],
       "DefaultBidLists": [
        {
          "BidListId": "efgh5678"
        },
        {
          "BidListId": "ijkl9012"
        }
    ]
    // Include other required fields.
}

Include campaign default bid lists in a new ad group

To include campaign default bid lists in a new ad group, use the POST /v3/adgroup endpoint. All default bid lists associated with the campaign are automatically applied this ad group upon its creation. If the same bid list is already applied to the ad group, it will be included only once. The applied lists can be removed, as needed.

TIP: If you want to include other bid lists to the ad group in addition to the campaign default bid lists, include the AssociatedBidLists array with the IDs of the additional bid lists in the request and set them as enabled.

{
   "CampaignId":"mnop3456",
   "AdGroupName":"AD_GROUP_NAME_PLACEHOLDER",
   "IncludeDefaultsFromCampaign": true
   // Include other required fields.
}