Release Notes

Release Notes

 

For information about the changes to the Bing Ads services for each release, see the following sections.

October 2015

For information about the changes to the Bing Ads services included in this release, see the following sections.

Bing Ads API Version 10

Bing Ads API Version 10 Ad Insight, Bulk, and Campaign Management services are now generally available in production and sandbox.

System_CAPS_ICON_note.jpg Note


The Ad Intelligence, Bulk, Campaign Management, and Optimizer Version 9 services are deprecated and are scheduled to be sunset at the beginning of the third calendar quarter of 2016. You must migrate to the Ad Insight, Bulk, and Campaign Management Version 10 services.

For more information, see Migrating from Bing Ads API Version 9 to Version 10.

Web Service NameProductionSandbox
Ad Insighthttps://adinsight.api.bingads.microsoft.com/Api/Advertiser/AdInsight/V10/AdInsightService.svchttps://adinsight.api.sandbox.bingads.microsoft.com/Api/Advertiser/AdInsight/V10/AdInsightService.svc
Bulkhttps://bulk.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/V10/BulkService.svchttps://bulk.api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/V10/BulkService.svc
Campaign Managementhttps://campaign.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/V10/CampaignManagementService.svchttps://campaign.api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/V10/CampaignManagementService.svc

Campaign Management Version 10

The CampaignType element is now required when calling GetCampaignsByAccountId and GetCampaignsByIds.

Software Development Kit (SDK) Updates

The Bing Ads .NET, Java, and Python SDKs are updated with support for Bing Ads API Version 10. For more information, see Bing Ads Client Libraries.

July 2015

For information about the changes to the Bing Ads services included in this release, see the following sections.

Bulk Version 10

Format Version 4.0

Support for Bulk file format version 3.0 is removed. Bing Ads API Version 10 now only supports format version 4.0. The following records have changed between format version 3.0 and 4.0.

  • The Mobile Ad record is removed. Bing Ads no longer supports WAP mobile ads.

  • The Product Ad Extension, Campaign Product Ad Extension, and Ad Group Product Target records are removed. Product ad extensions are not supported in Bing Ads Version 10. For product ads you should use Bing Shopping Campaigns instead.

  • The COUNTRY_CODE column is renamed to Country Code. This impacts the following existing record types: Call Ad Extension, Campaign, and Location Ad Extension.

  • In the Ad Group record, the Search Broad Bid column is renamed Search Bid and corresponds to the new SearchBid element of the Ad Group object in the Campaign Management service.

  • The Campaign Type field is now required when adding a new campaign using the Campaign record. In previous format versions SearchAndContent was used as the default value if Campaign Type was not specified.

  • For the Image Ad Extension record, the Media Id column is renamed Media Ids and accepts multiple media identifiers which must be semicolon delimited.

Location Target Version

The LocationTargetVersion element is removed from the DownloadCampaignsByAccountIds and DownloadCampaignsByCampaignIds operations. The service will always return locations according to Nielsen DMA® codes. For more information, see Geographical Location Codes.

Error Field Path

The Field Path field in the Bulk file now returns the name of the record's field where the error occurred. The name is formatted without spaces according to the element of the corresponding Campaign Management data object. For example if the Tracking Template field of a Campaign record contains invalid text, the value of this Field Path is TrackingUrlTemplate, which corresponds to the TrackingUrlTemplate element of the Campaign object.

System_CAPS_ICON_note.jpg Note


This field is only supported for Mobile Final Url, Final Url, Tracking Template, and Custom Parameter fields of the respective Campaign, Ad Group, Campaign, Product Ad, Ad Group Product Partition, Keyword, and Sitelink Ad Extension records.

Campaign Management Version 10

Ad Group Search Bid

The SearchBid element is added to the Ad Group object, and replaces the BroadMatchBid, ExactMatchBid, and PhraseMatchBid elements. You can set a default bid for all search match types (broad, exact, and phrase) using this new element. You can no longer set different ad group level bids for broad, exact, and phrase match types. You can still override the bids for each distinct Keyword match type.

Mobile Ads

Bing Ads no longer supports WAP mobile ads. The MobileAd Data Object is not available in Bing Ads Version 10.

Product Ads

Product ad extensions are not supported in Bing Ads Version 10. For product ads you should use Bing Shopping Campaigns instead. The following programming elements are not available in Bing Ads Version 10.

  • Product Data Object

  • ProductAdExtension Data Object

System_CAPS_ICON_note.jpg Note


The AddAdGroupCriterions, DeleteAdGroupCriterions, and UpdateAdGroupCriterions operations remain in the interface and are reserved for future use. Currently there are no ad group criterions that can be used with those operations.

Location Target Version

The LocationTargetVersion element is removed from the GetTargetsByAdGroupIds, GetTargetsByCampaignIds, and GetTargetsByIds operations. The service will always return locations according to Nielsen DMA® codes. For more information, see Geographical Location Codes.

Native Ads

To avoid breaking changes in Bing Ads version 9, some optional request elements were added to the following service operations. The elements have been removed in Bing Ads version 10.

Campaign Level Conversion Tracking

The ConversionTrackingEnabled element is removed from the Campaign object. Campaign-level conversion tracking has already sunset, and this element is no longer used even in Bing Ads version 9.

BatchError FieldPath

The FieldPath element of a BatchError now returns the name of the data object's element where the error occurred. For example if the TrackingUrlTemplate of a Campaign contains invalid text, the value of this FieldPath element is TrackingUrlTemplate.

System_CAPS_ICON_note.jpg Note


This element is only supported for FinalAppUrls, FinalMobileUrls, FinalUrls, TrackingUrlTemplate, and UrlCustomParameters elements of the respective Campaign, Ad Group, TextAd, ProductAd, BiddableAdGroupCriterion, Keyword, and SiteLink objects.

Reporting Version 9

The ProductDimensionPerformanceReportColumn Value Set has been changed. The following elements have been removed.

  • AdStatus

  • SellerName

  • AverageCPM

Software Development Kit (SDK) Updates

The Bing Ads .NET, Java, and Python SDKs are updated with support for Native Ads and Bing Shopping Campaign Bulk operations. For more information, see Bing Ads Client Libraries.

June 2015

For information about the changes to the Bing Ads services included in this release, see the following sections.

Ad Insight Version 10

Merged Ad Intelligence and Optimizer

Version 10 of the Ad Insight service is available for preview in sandbox.

The Ad Intelligence and Optimizer services that were available in Bing Ads API Version 9 are merged together and named Ad Insight.

The namespace is https://bingads.microsoft.com/AdInsight/v10.

The sandbox endpoint is https://adinsight.api.sandbox.bingads.microsoft.com/Api/Advertiser/AdInsight/V10/AdInsightService.svc.

Moved to Ad Insight from the Optimizer Service

These service operations have been moved from the version 9 Optimizer service to the new Ad Insight service.

These data objects have been moved to the new Ad Insight service.

These value sets have been moved to the new Ad Insight service.

Optimizer Features Sunset

These service operations will sunset with version 9 of the Optimizer service.

  • ApplyOpportunities

    System_CAPS_ICON_note.jpg Note


    To apply the suggested bid, budget, and keyword opportunities, you can use the update operations provided with the Bulk or Campaign Management services.

  • GetBudgetLandscape

    System_CAPS_ICON_note.jpg Note


    Budget landscape data is available in the new Ad Insight service. The response for GetBudgetOpportunities now includes a list of BudgetPoint objects.

These data objects will sunset with version 9 of the Optimizer service.

  • BidOpportunityModifier

  • BroadMatchOpportunityModifier

  • BudgetLandscapePoint

  • BudgetOpportunityModifier

  • CampaignBudgetLandscape

  • KeywordOpportunityModifier

  • OpportunityModifier

Budget Landscape

The GetBudgetLandscape operation is not carried forward with Ad Insight version 10, and will be sunset with version 9 of the Optimizer service.

With Ad Insight version 10, you can get budget landscape data using the GetBudgetOpportunities operation. Each returned BudgetOpportunity now includes BudgetPoints, which is a list of BudgetPoint objects representing the budget landscape.

In version 10, each BudgetPoint includes weekly impressions, clicks, and cost estimates instead of the daily estimates provided in version 9.

Opportunity Expiration Date

The ExpirationDate element is removed from the Opportunity object. Expired opportunities will not be returned by the Ad Insight service.

Bid Opportunity Type

The IncreaseTraffic value is removed from the BidOpportunityType value set.

Opportunities by Account

The AccountId request element is removed from the GetBidOpportunities, GetBudgetOpportunities, and GetKeywordOpportunities operations.

In Ad Insight version 10, the CustomerAccountId request header element determines the account used for the provided opportunities.

Keyword Data by Device

The Device element is added to the following objects.

Given the above update, the Device element is removed from the following objects.

The Device and HistoricalSearchCounts elements are removed from the KeywordSearchCount object. They are replaced by the SearchCountsByAttributes element, which is a list of SearchCountsByAttributes. Each SearchCountsByAttributes object contains a list of keyword historical search counts for the corresponding device.

Ad Group Estimated Bid

The data type of the AdGroupEstimatedBid response element of the GetEstimatedBidByKeywords operation is changed from AdGroupEstimatedBid to EstimatedBidAndTraffic.

The name and data type of the request property used by GetEstimatedBidByKeywords to determine the bid level is changed from GetBidsAtLevel (int) to EntityLevelBid (string). You can now specify either Keyword, AdGroup, or AllEntities.

Broad Match Keyword Opportunity

The following elements are moved from the KeywordOpportunity to BroadMatchKeywordOpportunity data object.

  • AverageCPC

  • AverageCTR

  • ClickShare

Previously the BroadMatchKeywordOpportunity object inherited those elements from KeywordOpportunity.

Budget Landscape

The response for GetBudgetOpportunities now includes a list of BudgetPoint objects.

Time Interval

The TimeInterval value set is updated to reflect the true intervals.

  • Last30Days is updated to LastMonth.

  • Last7Days is updated to LastWeek.

Bulk Version 10

Updated the Version Number

Version 10 of the Bulk service is available for preview in sandbox.

The namespace has been changed to reflect the new version number of this release; The namespace is https://bingads.microsoft.com/CampaignManagement/v10.

The sandbox endpoint is https://bulk.api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/V10/BulkService.svc.

Bulk Status Operations Renamed

The GetDetailedBulkUploadStatus operation is renamed GetBulkUploadStatus, which replaces the version 9 GetBulkUploadStatus operation.

The GetDetailedBulkDownloadStatus operation is renamed GetBulkDownloadStatus, which replaces the version 9 GetDownloadStatus operation.

Download Compression Type

You can now specify either the GZip or ZIP CompressionType when calling the DownloadCampaignsByAccountIds and DownloadCampaignsByCampaignIds operations.

Campaign Management Version 10

Updated the Version Number

Version 10 of the Campaign Management service is available for preview in sandbox.

The namespace has been changed to reflect the new version number for this release. The new namespace name is https://bingads.microsoft.com/CampaignManagement/v10. For the production and sandbox endpoints, see Bing Ads Web Service Addresses.

The namespace has been changed to reflect the new version number for this release.; The namespace is https://bingads.microsoft.com/CampaignManagement/v10.

The sandbox endpoint is https://campaign.api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/V10/CampaignManagementService.svc.

Target2 renamed as Target

In Bing Ads API version 9, the "Target2" object model was introduced to avoid breaking changes, instead of adding new elements to the version 9 Target. The following objects and operations are renamed in version 10.

Version 9Version 10
Target2Target
LocationTarget2LocationTarget
RadiusTarget2RadiusTarget
RadiusTargetBid2RadiusTargetBid
AddTargetsToLibrary2AddTargetsToLibrary
GetTargetsByAdGroupIds2GetTargetsByAdGroupIds
GetTargetsByCampaignIds2GetTargetsByCampaignIds
GetTargetsByIds2GetTargetsByIds
UpdateTargetsInLibrary2UpdateTargetsInLibrary

The following objects and value sets related to the legacy version 9 target model are also removed.

  • DayTarget Data Object

  • DayTargetBid Data Object

  • HourTarget Data Object

  • HourTargetBid Data Object

  • NetworkTarget Data Object

  • NetworkTargetBid Data Object

  • HourRange Value Set

  • NetworkType Value Set

Negative Keyword Legacy Operations Removed

The SetNegativeKeywordsToCampaigns and SetNegativeKeywordsToAdGroups operations are removed. AddNegativeKeywordsToEntities and DeleteNegativeKeywordsFromEntities should be used instead of the SetNegativeKeywordsToCampaigns and SetNegativeKeywordsToAdGroups operations.

The GetNegativeKeywordsByCampaignIds and GetNegativeKeywordsByAdGroupIds operations are removed. GetNegativeKeywordsByEntityIds should be used instead of the GetNegativeKeywordsByCampaignIds and GetNegativeKeywordsByAdGroupIds operations.

In turn the AdGroupNegativeKeywords Data Object``CampaignNegativeKeywords Data Object are also removed.

Ad Group Status

The Expired value is added to the AdGroupStatus Value Set. Previously expired ad groups were returned with a Deleted status, although the true status has always been expired. The Deleted value is retained in version 10, but is now reserved for internal use.

The Draft value is removed from the AdGroupStatus Value Set. In turn, the SubmitAdGroupForApproval operation is also removed. To pause and resume ad groups, use the UpdateAdGroups operation.

Partial Success and Partial Errors

Partial success means that when adding, updating, or deleting entities in batches of one or more, the operation may succeed for some and fail for part of the batch. For each list index where an entity was not added, the corresponding element will be null. The PartialErrors element represents an array of BatchError objects that contain details for any entities that were not successfully added, updated, or deleted. The list only includes a BatchError for unsuccessful attempts, and does not include null elements at the index of each successfully added entity. Similarly some operations return NestedPartialErrors as a list of BatchErrorCollection, or a two dimensional BatchError.

The following operations now include PartialErrors in the response.

The following operations now include NestedPartialErrors in the response.

For more information and a complete list of operations that support partial success, see Partial Success using the Campaign Management Service.

Editorial Operations Require Ad Group Identifiers

The AppealEditorialRejections and GetEditorialReasonsByIds operations now require the ad group identifier in addition to ad or keyword ID. The EntityIds element is removed from both operations and replaced by EntityIdToParentIdAssociations, which is a list of EntityIdToParentIdAssociation. Each EntityIdToParentIdAssociation contains the unique system identifier of an entity such as ad or keyword, and the identifier of its parent. An ad group is the parent of an ad or keyword.

Additionally, an AdGroupId element is added to the EditorialReasonCollection data object.

Get Criterions

The GetAdGroupCriterionsByAdGroupId operation is removed. To get all ad group criterions for an ad group, you can leave AdGroupCriterionIds null in the request to GetAdGroupCriterionsByIds.

The GetCampaignCriterionsByCampaignId operation is removed. To get all campaign criterions for a campaign, you can leave CampaignCriterionIds null in the request to GetCampaignCriterionsByIds.

Upgrade to Final URLs

Final URLs will eventually replace Destination URLs that are specified today for your ads and keywords. Version 9 will not support Final URLs, so you'll need to use Version 10.

System_CAPS_ICON_note.jpg Note


Details on the migration plan from Destination URLs to Final URLs are coming soon.

The FinalAppUrls, FinalMobileUrls, and FinalUrls elements are added to the following objects.

Tracking Templates and Custom Parameters

Tracking templates and custom parameters are added to provide more flexibility and simplify management of Dynamic Text Substitution for URL tracking.

System_CAPS_ICON_note.jpg Note


Details on support for Tracking Templates and Custom Parameters are coming soon.

The TrackingUrlTemplate and UrlCustomParameters elements are added to the following objects.

Reporting

The AdDistributionReportFilter has been added to these report filters:

The AdDistributionReportFilter value set includes a value for Native ads that is reserved for future use.

Updated Length of Download Request ID

A request ID is used by clients when downloading reports with the Reporting service and when downloading campaign settings using the Bulk service. The request ID is returned immediately once the download is requested. The client can then use the request ID to poll for status and download the data when processing is completed. Previously the request ID is a string of length 10, and with this change the length of the string can be up to 40. The string currently contains only numbers, for example 1234567890; however, your application should be prepared for any string value.

The report ID is used by these request and response messages:

April 2015

For information about the changes to the Bing Ads services included in this release, see the following sections.

Campaign Management Version 9

Bing Shopping Campaigns

A Bing Shopping campaign enables you to advertise the products from your Bing Merchant Center store product catalog. Product ads from a Bing Shopping campaign include details about the product, an image, and optional promotional text. For more information, see Bing Shopping Campaigns and the following reference documentation.

The following service operations are reserved for working with Bing Shopping campaigns.

To support Bing Shopping campaigns, the CampaignType and Settings elements are added to the Campaign object. When you get a campaign object using GetCampaignsByAccountId or GetCampaignsByIds, these new elements are only returned for Bing Shopping campaigns when you set the respective operation's CampaignType element to Shopping.

Reporting Version 9

Bing Shopping Campaigns

A Bing Shopping campaign enables you to advertise the products from your Bing Merchant Center store product catalog. Product ads from a Bing Shopping campaign include details about the product, an image, and optional promotional text. For more information, see Bing Shopping Campaigns and the following reference documentation.

The following reports are added for Bing Shopping campaigns.

Report NameDescriptionRequestFilterColumns
Product DimensionnDefines a product dimension performance report request that aggregates the performance data by product category, custom label, title, and type for a specified time period. You can include details in the report such as impressions, clicks, and spend that you can use to identify whether or not the Bing Shopping products are performing well.ProductDimensionPerformanceReportRequestProductDimensionPerformanceReportFilterProductDimensionPerformanceReportColumn
Product PartitionDefines a product partition performance report request that aggregates the performance data by product group and product partition type for a specified time period. You can include details in the report such as impressions, clicks, and spend that you can use to identify whether or not the Bing Shopping products are performing well.ProductPartitionPerformanceReportRequestProductPartitionPerformanceReportFilterProductPartitionPerformanceReportColumn

Negative Keyword Conflict Report

The NegativeKeywordConflictReportColumn value set has been updated to include:

  • BidMatchType

  • NegativeKeywordListId

  • NegativeKeywordList

  • NegativeKeywordId

  • NegativeKeywordMatchType

Use these IDs to find and resolve negative keyword conflicts when the keywords are shared via a list.
For more information refer to the Bing Ads API blog post Enhanced Negative Keyword Conflicts Report.

January 2015

For information about the changes to the Bing Ads services included in this release, see the following sections.

Optimizer Version 9

The KeywordOpportunity data object has been updated to include:

  • EstimatedIncreaseInClicks

  • EstimatedIncreaseInCost

  • EstimatedIncreaseInImpressions

These elements have been removed from the BroadMatchKeywordOpportunity data object. This object inherits from KeywordOpportunity, so the elements remain available in the BroadMatchKeywordOpportunity data object.

This change allows users to retrieve keyword opportunities using the BroadMatch and CampaignContext settings in the KeywordOpportunityType.

In the GetKeywordOpportunities, set the IncludeEstimations flag to true to include the estimated impact elements in the response body of the KeywordOpportunity object. These elements are part of the KeywordOpportunity data object and can be used in objects that inherit from KeywordOpportunity, such as BroadMatchKeywordOpportunity.

Reporting Version 9

Support for Universal Event Tracking

Additional support for Universal Event Tracking has been added to the Reporting API.

New Elements/AttributesAvailable in these Report ColumnsUse these Report Requests
AverageDurationPerVisit

AveragePagesPerVisit

BounceRate

TotalVisits
AccountPerformanceReportColumn

AdGroupPerformanceReportColumn

CampaignPerformanceReportColumn

KeywordPerformanceReportColumn
AccountPerformanceReportRequest

AdGroupPerformanceReportRequest

CampaignPerformanceReportRequest

KeywordPerformanceReportRequest
GoalIdGoalsAndFunnelsReportColumnGoalsAndFunnelsReportRequest

For more information about using the Reporting service to analyze Campaign Analytics data, see the Getting Reports section of the topic Track sales and other conversions.

October 2014

For information about the changes to the Bing Ads services included in this release, see the following sections.

Reporting Version 9

Universal Event Tracking (UET)

Universal Event Tracking replaces the current Campaign Analytics conversion tracking.

For more information about using Universal Event Tracking, see the topic Track sales and other conversions.

Campaign Analytics Scripts

Campaign Analytics Scripts are being deprecated. For more information see the deprecation warning on the Managing Campaign Analytics Scripts page.

September 2014

For information about the changes to the Bing Ads services included in this release, see the following sections.

Campaign Management

Targets

System_CAPS_ICON_note.jpg Note


Previously this feature was only available for pilot participants.

The Target2 Data Object is now generally available and includes the DayTimeTarget and LocationTarget2 objects, which are not included in the legacy Target object.

The following service operations are reserved for working with Target2 objects.

The following service operations may be used with either Target or Target2 objects.

The following service operations are reserved for working with the legacy Target objects.

For code examples that show how to associate targets with a campaign and ad group, see Targets in C# | Targets in Java | Targets in PHP.

Negative Keywords

System_CAPS_ICON_note.jpg Note


Previously this feature was only available for pilot participants.

The NegativeKeyword Data Object is now generally available and defines a negative keyword with match type. Each negative keyword can be added and deleted, but cannot be updated.

System_CAPS_ICON_note.jpg Note


The same negative keyword and match type can be added to all campaigns, ad groups, and negative keyword lists if you choose. Each instance must be added and associated individually and would be assigned a unique negative keyword identifier.

You may choose to associate an exclusive set of negative keywords to an individual campaign or ad group. An exclusive set of negative keywords cannot be shared with other campaigns or ad groups. You can manage an exclusive set of negative keywords with the AddNegativeKeywordsToEntities, DeleteNegativeKeywordsFromEntities, and GetNegativeKeywordsByEntityIds operations.

Negative keywords can also be added and deleted from a shared negative keyword list. The negative keyword list can be shared or associated with multiple campaigns.

System_CAPS_ICON_note.jpg Note


Negative keyword lists cannot be associated with an ad group. An ad group can only be assigned an exclusive set of negative keywords. In addition to the exclusive set of negative keywords that can be assigned to a campaign, each campaign can be associated with one negative keyword list.

To create a negative keyword list, call the AddSharedEntity operation and pass a NegativeKeywordList, which inherits from both SharedList and SharedEntity.You can create up to 20 negative keyword lists per account and share or associate them with any campaign in the same account. You can get existing negative keyword lists by calling the GetSharedEntitiesByAccountId operation. You can update the name of the negative keyword list by calling the UpdateSharedEntities operation. You can delete the negative keyword list by calling the DeleteSharedEntities operation.

To add negative keywords to a negative keyword list, call the AddListItemsToSharedList operation and pass a list of NegativeKeyword, which inherits from SharedListItem.You can add up to 10,000 negative keywords to each negative keyword list. You can get negative keywords within a specified list by calling the GetListItemsBySharedList operation. Negative keywords can be removed from a list by calling the DeleteListItemsFromSharedList operation.

To associate a negative keyword list with a campaign, specify an array of SharedEntityAssociation with the SetSharedEntityAssociations service operation. Each SharedEntityAssociation should include the type of entity (currently only Campaign is supported), campaign identifier, and negative keyword list identifier. You can get the associations by entity identifier or negative keyword list identifier by calling the respective GetSharedEntityAssociationsByEntityIds and GetSharedEntityAssociationsBySharedEntityIds operations. You can remove the association between the campaign and negative keyword list by calling the DeleteSharedEntityAssociations operation.

For code examples that show how to associate negative keywords and negative keyword lists with a campaign, see Negative Keywords in C# | Negative Keywords in Java | Negative Keywords in PHP.

Reporting Version 9

The AdExtensionDimensionReport is deprecated and no longer supported. A call to generate this report will throw an exception.

August 2014

For information about the changes to the Bing Ads services included in this release, see the following sections.

Ad Intelligence Version 9

Keyword Suggestion Types

The following values are now supported in the SuggestionType element of the SuggestKeywordsFromExistingKeywords operation.

  • 2 - Now supported for Italy (IT), Netherlands (NL), and Norway (NO), in addition to existing markets.

  • 4 - Now supported for Taiwan (TW), in addition to existing markets.

For a complete list of possible providers, the language and country restrictions of each provider, and the default provider by country, see the Remarks section in SuggestKeywordsFromExistingKeywords.

Bulk Version 9

Format Version 3.0

The latest supported value for the FormatVersion element of DownloadCampaignsByAccountIds and DownloadCampaignsByCampaignIds service operations is 3.0. The bulk format version is separate from the Bing Ads API version. Format versions enable a flexible upgrade path to adopt the latest supported features without breaking your application. For more information, see Bulk File Schema.

System_CAPS_ICON_important.jpg Important


Before you upgrade to the latest format version, you should read Bulk File Deprecated Record Types. If you currently use any of the deprecated records, you should read about and understand the differences between the deprecated version and the latest version of the Bulk File Record Types.

Campaign Management Version 9

Image Ad Extension

The Description element is added to the ImageAdExtension object.

This element can be used by the advertiser, agency, or account manager to track, label, or manage image media. This description is not displayed with the ad or image.

Media Associations

The GetMediaAssociations operation is added and returns a list of KeywordOpportunities objects.

This operation gets the media associations of the specified entity type from an account’s media library. For example you can get the identifier of media for an image ad extension associated with an ad group.

Customer Billing Version 9

Order By Field for Search Operations

The LifeCycleStatus value is added to the OrderByField value set.

System_CAPS_ICON_note.jpg Note


This value is reserved for future use.

Customer Management Version 9

Order By Field for Search Operations

The LifeCycleStatus value is added to the OrderByField value set.

When calling SearchAccounts, for example you may choose to order the results by account life cycle status.

Reporting Version 9

Exclude Zero Click Search Term Data

The ExcludeZeroClicks element is added to the SearchQueryPerformanceReportFilter, and can be used when submitting the SearchQueryPerformanceReportRequest.

If the value of the ExcludeZeroClicks element is set to true, the report will exclude data for search terms that had one or more ad impressions but resulted in zero clicks.

July 2014

For information about the changes to the Bing Ads services included in this release, see the following sections.

Campaign Management Version 9

ActiveLimited Editorial Status

The ActiveLimited value is now available in the EditorialStatus element of the Ad, BiddableAdGroupCriterion, and Keyword data objects.

This value indicates that the entity passed editorial review in one or more markets, and one or more elements of the entity is undergoing editorial review in another market. For example, a keyword that passed editorial review for Canada and is still pending review in the United States.

Customer Management Version 9

User Invitations

The SendUserInvitation operation is added. You can send an invitation for a Microsoft account user to manage one or more Bing Ads customer accounts. When the invitation is accepted, the user's Microsoft account is linked to the specified Bing Ads customer accounts. For more information about user authentication, see Managing User Authentication with OAuth.

To get pending user invitations you can use the SearchUserInvitations operation and filter by CustomerId.

June 2014

For information about the changes to the Bing Ads services included in this release, see the following sections.

Ad Intelligence Version 9

Ad Group Bid Landscape

The GetBidLandscapeByAdGroupIds service operation is added and takes our bid tuning functionality one step further than GetBidLandscapeByKeywordIds. Given a list of existing ad groups, this operation returns for each a list of suggested bids and estimated performance statistics. You can use the landscape view of multiple bid points with estimated traffic for the same ad group to help make decisions about how to adjust your ad group level default bid to optimize for clicks, impressions, and cost. For example you might use the resulting data to visualize a clicks to cost curve or a bid to impressions curve.

You can get bid landscape for an entire ad group in either default or uniform mode. For more information, see AdGroupBidLandscapeType Value Set.

Bulk Version 9

BulkDownloadEntity

The NegativeKeywordList, NegativeKeyword, and CampaignNegativeKeywordList elements of the BulkDownloadEntity value set have been renamed to NegativeKeywordLists, SharedNegativeKeywords, and CampaignNegativeKeywordListAssosciations respectively.

Image Ad Extensions

Bulk upload and download now support Image Ad Extensions. The record types Image Ad Extension and Ad Group Image Ad Extension have been added to the bulk file schema and are documented in the Bulk File Record Types topic.

Radius Target Bid Units

A new column, Unit, has been added to the Campaign Radius Target and Ad Group Radius Target record types. This column corresponds to the RadiusUnit element of the RadiusTargetBid2 data object.

Campaign Management Version 9

Negative Keywords

The NegativeKeyword Data Object is added and defines a negative keyword with match type. Each negative keyword can be added and deleted, but cannot be updated.

>

The same negative keyword and match type can be added to all campaigns, ad groups, and negative keyword lists if you choose. Each instance must be added and associated individually and would be assigned a unique negative keyword identifier.

You may choose to associate an exclusive set of negative keywords to an individual campaign or ad group. An exclusive set of negative keywords cannot be shared with other campaigns or ad groups. You can manage an exclusive set of negative keywords with the AddNegativeKeywordsToEntities, DeleteNegativeKeywordsFromEntities, and GetNegativeKeywordsByEntityIds operations.

Negative keywords can also be added and deleted from a shared negative keyword list. The negative keyword list can be shared or associated with multiple campaigns.

System_CAPS_ICON_note.jpg Note


Negative keyword lists cannot be associated with an ad group. An ad group can only be assigned an exclusive set of negative keywords. In addition to the exclusive set of negative keywords that can be assigned to a campaign, each campaign can be associated with one negative keyword list.

To create a negative keyword list, call the AddSharedEntity operation and pass a NegativeKeywordList, which inherits from both SharedList and SharedEntity.You can create up to 20 negative keyword lists per account and share or associate them with any campaign in the same account. You can get existing negative keyword lists by calling the GetSharedEntitiesByAccountId operation. You can update the name of the negative keyword list by calling the UpdateSharedEntities operation. You can delete the negative keyword list by calling the DeleteSharedEntities operation.

To add negative keywords to a negative keyword list, call the AddListItemsToSharedList operation and pass a list of NegativeKeyword, which inherits from SharedListItem.You can add up to 10,000 negative keywords to each negative keyword list. You can get negative keywords within a specified list by calling the GetListItemsBySharedList operation. Negative keywords can be removed from a list by calling the DeleteListItemsFromSharedList operation.

To associate a negative keyword list with a campaign, specify an array of SharedEntityAssociation with the SetSharedEntityAssociations service operation. Each SharedEntityAssociation should include the type of entity (currently only Campaign is supported), campaign identifier, and negative keyword list identifier. You can get the associations by entity identifier or negative keyword list identifier by calling the respective GetSharedEntityAssociationsByEntityIds and GetSharedEntityAssociationsBySharedEntityIds operations. You can remove the association between the campaign and negative keyword list by calling the DeleteSharedEntityAssociations operation.

For code examples that show how to associate negative keywords and negative keyword lists with a campaign, see Negative Keywords in C# | Negative Keywords in Java | Negative Keywords in PHP.

Targets

The Target2 Data Object is added and includes the DayTimeTarget and LocationTarget2 objects, which are not included in the legacy Target object.

The following service operations are reserved for working with Target2 objects.

The following service operations may be used with either Target or Target2 objects.

The following service operations are reserved for working with the legacy Target objects.

For code examples that show how to associate targets with a campaign and ad group, see Targets in C# | Targets in Java | Targets in PHP.

Replace Target Associations

The ReplaceAssociation element is added to the SetTargetToAdGroup and SetTargetToCampaign service operations.

If the specified ad group or campaign entity is already associated with a target, this element determines whether to replace the existing association between the entity and target with the specified TargetId.

If set to True the operation will replace the existing association between the entity and target with the specified TargetId.

The default value is False if not otherwise specified. If the value is False and if an association already exists, the operation will throw error 1427, CampaignServiceTargetAlreadyAssociatedWithEntity.

System_CAPS_ICON_note.jpg Note


If the specified entity is not currently associated with a target, this element has no effect.

Granular Radius Target Bid

Previously Bing Ads only allowed radius targets by increments of 5, for example 5, 10, 20, as the radius of a radius target bid. Positive integer increments from 1 to 500 (for example 1, 2, 3, 499, and 500) are now supported. Please ensure your clients can handle such values in the Radius element of the RadiusTargetBid and RadiusTargetBid2 moving forward.

Image Ad Extensions

The ImageAdExtension Data Object is added and defines an ad extension that specifies an image with alternative text to include in a text ad. The ImageAdExtension object derives from the AdExtension object and can be managed using existing ad extensions operations, for example AddAdExtensions and SetAdExtensionsAssociations. For more information, see Ad Extensions.

Before you can create an image ad extension, you must add valid media to your account's library with the AddMedia operation. Then you can get the media identifiers for image ad extensions with the GetMediaMetaDataByAccountId operation. Once you know the media meta data identifiers then you can alternatively call GetMediaMetaDataByIds.

Site Link Description

You can now add two additional lines of text with each site link in your ad extension. The Description1 and Description2 elements are added to the SiteLink Data Object.

Site Link Device Preference

You can now set the of the DevicePreference element of the SiteLink object to indicate whether you prefer to show site links on mobile devices or all devices.

Enhanced Exact Match

For accounts in the United States which have English language ad groups, Bing Ads automatically includes close variations of your exact match keywords, such as plural forms. For example, if your keyword is “motorcycle,” close variations would include “motorcycles".

If you don’t want your ads to show for close variations of your exact match keywords, then use the ForwardCompatibilityMap element of the Campaign Data Object and set the value of the KeywordVariantMatchEnabled key to False.

Customer Management Version 9

UTM AutoTag

Determines whether to append or replace the supported UTM tracking codes within all ad and keyword destination URLs for the account. To manage auto tag settings, use the ForwardCompatibilityMap element of the Account Data Object and set the value of the AutoTag key to one of the following supported values.

  • 0 - Bing Ads will not append any UTM tracking codes to your ad or keyword destination URL.

  • 1 - Bing Ads will automatically append the supported UTM tracking codes, and preserve any existing UTM tracking codes that you added to your ad or keyword's destination URL.

  • 2 - Bing Ads will automatically append the supported UTM tracking codes, and replace any of the existing and supported UTM tracking codes that you added to your ad or keyword's destination URL.

Optimizer Version 9

Unified Bid Opportunity

The GetBidOpportunities service operation is updated to support bid opportunities for client specified position goals, for example first page versus mainline ad position. When calling GetBidOpportunities, you can set the optional OpportunityType request element to one or more of the BidOpportunityType values.

System_CAPS_ICON_note.jpg Note


The operation will only return opportunities if there’s a suggested increase within 100% of your current bid that will help you achieve the specified goal.

Unified Keyword Opportunity

The GetKeywordOpportunities service operation is updated to support broad match keyword opportunities. When calling GetKeywordOpportunities, you can set the optional OpportunityType request element to one or more of the KeywordOpportunityType values. For example if you include only the BroadMatch keyword opportunity type, the operation would only return BroadMatchKeywordOpportunity objects. If you do not specify any opportunity type or include only the CampaignContext keyword opportunity type, the operation would only return KeywordOpportunity objects as before.

Opportunity Modifiers

The ApplyOpportunities service operation is updated and now enables you to apply a modified or customized opportunity. When calling ApplyOpportunities, you can set the optional OpportunityModifiers request element to include one or more of the OpportunityModifier objects. For example you can specify a bid different than the suggested opportunity by setting the Bid element of a BidOpportunityModifier object and including the object in a call to ApplyOpportunities.

System_CAPS_ICON_note.jpg Note


If specified, the OpportunityModifiers overrides any specified OpportunityKeys.

Reporting Version 9

Search Campaign Change History Report

The optional AccountNumber and AccountName columns are added to the SearchCampaignChangeHistoryReportColumn Value Set.

Reduced Impression Share Column Restrictions

For reports that include impression share performance statistics columns you can now include the BidMatchType, DeliveredMatchType, DeviceType, and Network attributes in the same report request. Likewise if you include any of those attribute columns, you can include any of the impression share performance statistics columns.

For information about standing attribute restrictions with impression share reports, please see Column Restrictions.

May 2014

For information about the changes to the Bing Ads services included in this release, see the following sections.

Customer Billing Version 9

Insertion Order

The following operations to enable agency management of insertion orders are added.

Customer Management Version 9

Search Accounts

The SearchAccounts operation is added, and you can search accounts by AccountId, AccountNumber, CustomerId, and UserId.

Reporting Version 9

Geo Location

The GeoLocationPerformanceReportRequest, GeoLocationPerformanceReportFilter, and GeoLocationPerformanceReportColumn are added.

System_CAPS_ICON_note.jpg Note


With the introduction of this new report, the GeographicalLocationReport programming elements are deprecated.

Product Offer

The ProductOfferPerformanceReportRequest, ProductOfferPerformanceReportFilter, and ProductOfferPerformanceReportColumn are added.

April 2014

For information about the changes to the Bing Ads services included in this release, see the following sections.

Ad Intelligence Version 9

Keyword Bid Landscape

The GetBidLandscapeByKeywordIds service operation is added. Given a list of existing keywords, this operation returns for each a list of suggested bids and estimated performance statistics from 1 to 7 days.

You can use the landscape view of multiple bid points with estimated traffic for the same keyword to help make decisions about how to adjust your keyword bid to optimize for clicks, impressions, and cost. For example you might use the resulting data to visualize a clicks to cost curve or a bid to impressions curve.

Bulk Version 9

Client Identifiers

The Client Id field is added to the bulk upload and upload results file. Client identifiers may be used to associate input records in the bulk upload file with output records in the results file. For example when adding new records you may set the Client Id field to a string value of your choosing. The Bing Ads system makes no modifications to your client identifiers and passes them through to the results file for the corresponding record. For more information, see Client Identifiers.

Campaign Management Version 9

Campaign Status Suspended

The Suspended value is added to the CampaignStatus Value Set, and indicates that your campaign has been suspended and no ads are eligible for delivery because of potentially fraudulent activity.

Customer Management Version 9

Client Link

The following operations to enable agency management of client accounts are added.

Linking enables any agency Super Admin to access and manage the specified client account. For more information, see Link to Client Accounts.

System_CAPS_ICON_note.jpg Note


Client link operations are currently not supported in sandbox.

Account Status Suspended

The Suspended value is added to the AccountLifeCycleStatus Value Set, and indicates that your account has been suspended and no ads are eligible for delivery because of potentially fraudulent activity.

Reporting Version 9

Entity Identifiers

One or more of the AccountId, CampaignId, and AdGroupId entity identifiers have been added to the following report column value sets.

Value SetColumns Added
AccountPerformanceReportColumnAccountId
AdDynamicTextPerformanceReportColumnAccountId
AdGroupPerformanceReportColumnAccountId
AdPerformanceReportColumnAccountId

CampaignId
AgeGenderDemographicReportColumnAccountId

AdGroupId

CampaignId
BudgetSummaryReportColumnAccountId

CampaignId
CampaignPerformanceReportColumnAccountId
DestinationUrlPerformanceReportColumnAccountId
GeographicalLocationReportColumnAccountId

AdGroupId

CampaignId
RichAdComponentPerformanceReportColumnAccountId
SearchCampaignChangeHistoryReportColumnAccountId

AdGroupId

CampaignId

March 2014

For information about the changes to the Bing Ads services included in this release, see the following sections.

Bulk Version 9

Detailed Download Status

The GetDetailedBulkDownloadStatus service operation now returns completion progress of a bulk download request in the PercentComplete response element.

Campaign Management Version 9

Granular Radius Target Bid

Currently Bing Ads only allows radius targets by increments of 5, for example 5, 10, 20, as the radius of a radius target bid. Positive integer increments from 1 to 500 (for example 1, 2, 3, 499, and 500) will be supported in a future update. Please ensure your clients can handle such values in the Radius element of the RadiusTargetBid moving forward.

Site Link Description

Soon you will be able to add two additional lines of text with each site link in your ad extension. The Description1 and Description2 elements are added to the SiteLink. Until the feature is available, these fields will be available in the WSDL only as stubs, and they cannot be specified nor will they be returned. In the meantime you should refresh your campaign management proxy to get the latest references.

Reporting Version 9

Ad Extension Detail Report

The ad extension detail report is added to the reporting service. Use this report to discover the effectiveness of individual ad extension items, for example each link of a sitelink extension.
You can request impressions, clicks, spend, and average cost per click of individual extension items. Once downloaded, this data can be sorted by the individual ad extension display name, ad extension ID, and ad extension type.

To use the report, submit the AdExtensionDetailReportRequest with an optional AdExtensionDetailReportFilter. Specify attribute and performance statistic columns with the AdExtensionDetailReportColumn. For more information, see Getting Reports.

Common Attributes and Performance Statistics

The following report column value sets are updated to include popular attribute and performance statistic columns.

The following attributes and performance statistics are now available in all of the reports listed above.

AttributesPerformance Statistics
BidMatchType

DeliveredMatchType

DeviceOS

DeviceType

Language

Network

TopVsOther
Assists

Clicks

ConversionRate

Conversions

CostPerAssist

CostPerConversion

Ctr

ExtendedCost

Impressions

ReturnOnAdSpend

Revenue

RevenuePerAssist

RevenuePerConversion

Spend

For more information, see Report Attributes and Performance Statistics.

Impression Share Column Restrictions

For reports that include impression share performance statistics columns you should not include the following attributes in the same report request. Likewise if you include any of the following attribute columns, you should exclude all of the impression share performance statistics columns.

  • BidMatchType

  • ClickType

  • DeliveredMatchType

  • DeviceOS

  • DeviceType

  • Network

  • TopVsOther

System_CAPS_ICON_important.jpg Important


In the Bing Ads web application, users are not allowed to select the restricted column combinations. Using the Bing Ads API the report submission will not fail, for example if you include BidMatchType and ImpressionLostToBidPercent; however, the fields returned in the downloaded report will be 0 (zero) in place of any meaningful data.

For more information, see Column Restrictions.

Report Aggregation for Impression Share

The Weekly, Monthly, Yearly, and Summary values of the ReportAggregation value set may now be specified when including the impression share columns within the following reports.

Search Query Report Impressions and CTR

Previously the number of impressions listed in a search query report might be just a fraction of the total impressions that are generated for a search query. The report would display only impressions that result in at least one click during a one-hour reporting period. For example, if a search query resulted in one or more clicks during hour one, all impressions during hour one were reported. If the same search query resulted in zero clicks during hour two, no impressions were reported for hour two. As a result, the click-through rate (CTR) may have been overstated.

With this release all impressions for search queries are reported, and the click-through rate (CTR) is represented accurately in the report.

Search Query Report Aggregation

You may now submit a SearchQueryPerformanceReportRequest with new aggregation values. The DayOfWeek, HourOfDay, and Yearly values are added to the SearchQueryReportAggregation value set.

February 2014

For information about the changes to the Bing Ads services included in this release, see the following sections.

Customer Management Version 9

Microsoft Account User

Previously when retrieving a User data object, the value of the UserName element varied as follows.

  • If the value of IsMigratedToMicrosoftAccount is false, this element contained the user's Bing Ads managed sign-in user name. The name is case-insensitive.

  • If the value of IsMigratedToMicrosoftAccount is true, and if the user never had a Bing Ads managed sign-in user name, this element contained the email address corresponding to the authenticated Microsoft Account.

  • If the value of IsMigratedToMicrosoftAccount is true, and if the user migrated from a Bing Ads managed sign-in user name, this element contained the user's Bing Ads managed sign-in user name.

Now when retrieving a User data object, the value of the UserName element varies as follows.

  • If the value of IsMigratedToMicrosoftAccount is false, this element contains the user's Bing Ads managed sign-in user name. The name is case-insensitive.

  • If the value of IsMigratedToMicrosoftAccount is true, this element contains the email address corresponding to the authenticated Microsoft Account.

System_CAPS_ICON_note.jpg Note


The email address of the Microsoft Account may differ from the Email element of the ContactInfo data object.

Reporting Version 9

Change History Report for Call and Sitelinks Ad Extensions

Change history reporting is now available for CallAdExtension and SitelinksAdExtension, including their associations to Campaign or Ad Group entities. You should submit a SearchCampaignChangeHistoryReportRequest using the SubmitGenerateReport service operation.

For more information, see Call extension and Sitelink extension within SearchCampaignChangeHistoryReportColumn Value Set.

January 2014

For information about the changes to the Bing Ads services included in this release, see the following sections.

Bulk Version 9

Detailed Download Status

The GetDetailedBulkDownloadStatus service operation is added, and GetDownloadStatus is deprecated. This operation provides the status for the bulk download.

System_CAPS_ICON_note.jpg Note


Completion progress of a bulk download request will also be available in a future release.

Detailed Upload Status

The GetDetailedBulkUploadStatus service operation is added, and GetBulkUploadStatus is deprecated. This operation provides the status and progress completion percentage for the bulk upload.

Campaign Management Version 9

ActiveLimited Editorial Status

The ActiveLimited value is added to the following value sets.

This value indicates that the entity passed editorial review in one or more markets, and one or more elements of the entity is undergoing editorial review in another market. For example, a keyword that passed editorial review for Canada and is still pending review in the United States.

December 2013

For information about the changes to the Bing Ads services included in this release, see the following sections.

Bulk Version 9

Format Version

The FormatVersion element is added to the request object of both DownloadCampaignsByAccountIds and DownloadCampaignsByCampaignIds service operations.

Shared Ad Extensions

With file format version 1.0, an ad extension and associated entity are specified in one record, for example Campaign Call Ad Extension. With file format version 2.0 you need only specify a shareable ad extension library item once, and then set an association to one or more entities. For file format version 2.0, the following ad extension record types are available for download and upload.

To download the shareable ad extensions, set FormatVersion to 2.0 and include the following BulkDownloadEntity values in the download request.

  • CallAdExtensions

  • LocationAdExtensions

  • ProductAdExtensions

  • SiteLinksAdExtensions

Negative Reference Key

When referring to a new ad extension record set the extension's Id field to a negative number of your choice. This custom identifier is known as a negative reference key. Then you may use the negative reference key within the Id field of a dependent record. For more information, see Reference Keys.

November 2013

For information about the changes to the Bing Ads services included in this release, see the following sections.

Ad Intelligence Version 9

Currencies

Support for the following currency values is added.

  • Baht (The Thai Baht)

  • MalaysianRinggit (The MalaysianRinggit)

  • PhilippinePeso (The Philippine Peso)

  • Rupiah (The Indonesian Rupiah)

System_CAPS_ICON_note.jpg Note


The Currency value set contains both supported and unsupported currencies. For information about supported currencies, see Currencies.

Error Handling

Authentication Token Expired

The AuthenticationTokenExpired error code (109) is introduced for catching Microsoft Account authentication errors. The InvalidCredentials error code (105) will still be returned if the specified AuthenticationToken header element is not and has never been valid. Code 109 indicates that the specified value used to be valid and has since expired. You should request a new token before the current access token expires, or catch the AuthenticationTokenExpired error code (109) and then request a refresh token. For more information, see Managing User Authentication with OAuth.

October 2013

For information about the changes to the Bing Ads services included in this release, see the following sections.

Customer Billing Version 9

Updated the Namespace

The new namespace name is https://bingads.microsoft.com/Billing/v9. For the production endpoint, see Bing Ads Web Service Addresses.

System_CAPS_ICON_note.jpg Note


The Customer Billing service is not supported in sandbox.

Production Availability

The Customer Billing service is now generally available in production at https://clientcenter.api.bingads.microsoft.com/Api/Billing/v9/CustomerBillingService.svc.

Billing Documents

Programming elements related to invoices are renamed as billing documents.

Customer Management Version 9

Updated the Namespace

The new namespace name is https://bingads.microsoft.com/Customer/v9. For the production and sandbox endpoints, see Bing Ads Web Service Addresses.

System_CAPS_ICON_important.jpg Important


The Customer Management sandbox endpoint is updated to https://clientcenter.api.sandbox.bingads.microsoft.com/Api/CustomerManagement/v9/CustomerManagementService.svc.

Production Availability

The Customer service is now generally available in production at https://clientcenter.api.bingads.microsoft.com/Api/CustomerManagement/v9/CustomerManagementService.svc.

Managing User Authentication

Permissions to access Bing Ads accounts should be managed with a linked Microsoft Account. For more information, see Managing User Authentication with OAuth.

The IsMigratedToMicrosoftAccount flag is added to the User object. Use the flag to determine whether the user can be authenticated using a Microsoft Account.

The AddUser operation and UserRole value set are removed.

The User element is removed from calls to the SignupCustomer operation. The response will no longer include a UserId element.

Getting the Current User

The UserId element of the GetUser operation is no longer required. To get details for the current authenticated user specified in the request header, set the UserId element to null or do not specify it in the request to GetUser.

Account and Application Type

Bing Ads services are used to manage advertising campaigns. The Publisher value is removed from the AccountType and ApplicationType value sets.

Reporting Version 9

Rich Ads

The rich ad component report is added.

The following programming elements for the rich ad component report are added.

Product Target Report

The following optional columns are added to the ProductTargetPerformanceReportColumn.

  • AccountStatus

  • AdGroupStatus

  • CampaignStatus

  • DestinationUrl

Search Query Report

The following optional columns are added to the SearchQueryPerformanceReportColumn.

  • AdGroupCriterionId

  • ProductTarget

September 2013

For information about the changes to the Bing Ads services included in this release, see the following sections.

Ad Intelligence Version 9

Production Availability

The Ad Intelligence service is now generally available in production at https://api.bingads.microsoft.com/Api/Advertiser/AdIntelligence/v9/AdIntelligenceService.svc.

Estimated Clicks and Impressions

The data type for estimated clicks and impressions elements in the following data objects are updated from int to double and long respectively.

Estimated Ad Position

The data type for the EstimatedAdPosition element of the EstimatedPositionAndTraffic object is updated from AdPosition to double.

Historical Search Count Date Range

For GetHistoricalSeachCount, the StartTimePeriod and EndTimePeriod elements are renamed StartDate and EndDate respectively.

Historical Search Count Data Type

The SearchCount element of the HistoricSearchCountPeriodic data object is updated from int to long.

Increased Bid Coverage

The GetIncreasedBidCoverage element is removed from the GetEstimatedBidByKeywordIds and GetEstimatedBidByKeywords operations. The version 9 operations return data fields equivalent to setting the GetIncreasedBidCoverage element True in version 8. An estimated minimum bid will be returned for all requested keywords, and NULL values can be returned in the EstimatedBidAndTraffic Data Object.

Estimates By Keyword Identifiers

You may now specify 1,000 keyword identifiers with each call to the GetEstimatedBidByKeywordIds and GetEstimatedPositionByKeywordIds service operations. This is an increase from the previous limit of 100 identifiers.

Bulk Version 9

Production Availability

The Bulk service is now generally available in production at https://api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v9/BulkService.svc.

Campaign Management Version 9

Production Availability

The Campaign Management service is now generally available in production at https://api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v9/CampaignManagementService.svc.

Ad Extension Associations

The string All is removed from the AssociationType value set. To get all extensions using GetAdExtensionIdsByAccountId, including those not associated with any entity, set the AssociationType element to NULL.

Customer Billing Version 9

Sandbox Availability

The Customer Billing service is available in Sandbox at https://clientcenter.api.sandbox.bingads.microsoft.com/Api/Billing/v9/CustomerBillingService.svc.

Updated the Version Number

The namespace has been changed to reflect the new version number for this release. The new namespace name is https://bingads.microsoft.com/CustomerBilling/v9. For the sandbox endpoint, see Bing Ads Web Service Addresses.

Customer Management Version 9

Sandbox Availability

The Customer Management service is available in Sandbox at https://clientcenter.api.sandbox.bingads.microsoft.com/Api/CustomerManagement/v9/CustomerManagementService.svc.

Updated the Version Number

The namespace has been changed to reflect the new version number for this release. The new namespace name is https://bingads.microsoft.com/CustomerManagement/v9. For the sandbox endpoint, see Bing Ads Web Service Addresses.

Customer Pilot Features

The GetCustomerPilotFeature operation is renamed GetCustomerPilotFeatures (plural). The new name reflects the list of items returned by the service.

Rename the GetCustomerPilotFeature operation as GetCustomerPilotFeatures.

User Life Cycle Status

The New value within the UserLifeCycleStatus value set is replaced with Pending.

Replace usage of the New value of the UserLifeCycleStatus value set with Pending.

Forward Compatibility

The ForwardCompatibilityMap element is added to the following objects and reserved for future use.

Account Payment Instruments

The following account payment elements are added to the AdvertiserAccount data object.

  • BackUpPaymentInstrumentId

  • BillingThresholdAmount

Optimizer Version 9

Production Availability

The Optimizer service is now generally available in production at https://api.bingads.microsoft.com/Api/Advertiser/Optimizer/v9/OptimizerService.svc.

Budget Landscape

The GetBudgetLandscape operation is added. The operation gets the campaign budget landscape and corresponding budget points for the specified campaign in an account. You may use the budget points to compare your current budget to the suggested budget and optimize your campaign budget.

Estimated Clicks and Impressions

The data type for estimated clicks and impressions elements in the following data objects are updated from int to double and long respectively.

Reporting Version 9

Production Availability

The Reporting service is now generally available in production at https://api.bingads.microsoft.com/Api/Advertiser/Reporting/v9/ReportingService.svc.

August 2013

For information about the changes to the Bing Ads services included in this release, see the following sections.

Bulk Version 9

Download Status

For the GetDownloadStatus response message, the Status element of type DownloadStatus is replaced by RequestStatus of type string.

Custom Dates

Elements of the PerformanceStatsDateRange object, CustomDateRangeEnd and CustomDateRangeStart, are updated from type DateTime to type Date.

Campaign Management Version 9

Product Ads

The GetBMCStoresByCustomerId operation is added and returns a list of Bing Merchant Center store information for the specified customer. The StoreId element of each BMCStore can be used when adding a ProductAdExtension.

Partial Success for Ads and Keywords

When adding, updating, or deleting ads or keywords in batches of one or more, the operation may succeed for some and fail for part of the batch.

The PartialErrors element is added to the response message for the following service operations.

The PartialErrors element represents an array of BatchError objects that contain details for any entities that were not successfully added, updated, or deleted.

If the BatchError objects are derived EditorialError objects, then the reason why the add or keyword failed editorial review will be included.

Reporting Version 9

Error Codes

The ReportingService prefix for all ErrorCode elements is removed.

Ad Extension By Ad Report

AdExtensionByAdsReportRequest (Ads plural) is replaced by AdExtensionByAdReportRequest (Ad singular).

AdExtensionByAdsReportColumn (Ads plural) is replaced by AdExtensionByAdReportColumn (Ad singular).

The AdExtensionByAdReportFilter is added, and includes the DeviceOSReportFilter and DeviceTypeReportFilter.

Geographical Location Report

To match its feature scope and for parity with the Bing Ads web application, the metro area demographic report is renamed as the geographical location report.

The MetroAreaDemographicReportRequest object is replaced by GeographicalLocationReportRequest.

The MetroAreaDemographicReportFilter object is replaced by GeographicalLocationReportFilter.

The MetroAreaDemographicReportColumn value set is replaced by GeographicalLocationReportColumn.

Country Code Filter

The CountryReportFilter value set is removed.

Within the GeographicalLocationReportFilter, the Country element of type CountryReportFilter is replaced by the CountryCode element as a list of string.

Entity Identifiers

Entity identifiers are renamed within the ad group and campaign report scope objects.

Within the AdGroupReportScope object ParentAccountId is replaced by AccountId, and ParentCampaignId is replaced by CampaignId.

Within the CampaignReportScope object ParentAccountId is replaced by AccountId.

Campaign Report Scope

You may specify individual campaigns for the BudgetSummaryReportRequest.

The data type of its Scope element is updated from AccountReportScope to AccountThroughCampaignReportScope.

Delivered Match Type

Within the following report columns, the MatchType column value is renamed DeliveredMatchType.

Rich Ads

The rich ad component report is removed.

The following programming elements for the rich ad component report are removed.

  • RichAdComponentPerformanceReportRequest

  • RichAdComponentPerformanceReportFilter

  • RichAdComponentPerformanceReportColumn

  • RichAdSubTypeFilter

  • ComponentTypeFilter

Device Filters

You may filter report results by device type and device operating system with the respective DeviceTypeReportFilter and DeviceOSReportFilter.

The DeviceOS element of type DeviceOSReportFilter is added to the following report filters.

The Filter element is added to AdExtensionByKeywordReportRequest and AdExtensionDimensionReportRequest.

The type of Filter for AdExtensionByKeywordReportRequest is AdExtensionByKeywordReportFilter and contains both DeviceTypeReportFilter and DeviceOSReportFilter.

The type of Filter for AdExtensionDimensionReportRequest is AdExtensionDimensionReportFilter and contains both DeviceTypeReportFilter and DeviceOSReportFilter.

Pricing Model Filter

You may filter publisher usage report results by pricing model with the new PricingModelReportFilter.

The PricingModel filter element of type PricingModelReportFilter is added to the PublisherUsagePerformanceReportFilter.

Network

You may optionally specify Network as one the following report columns, and the report will include a column that contains the network of the ad group that contains the ad.

Top Versus Other

You may optionally specify TopVsOther as one the following report columns, and the report will include a column that indicates whether the ad impression appeared in a top position or elsewhere.

Ad Status

You may optionally specify AdStatus as one the AdPerformanceReportColumn values, and the report will include a column that indicates the current status of the corresponding ad.

July 2013

For information about the changes to the Bing Ads services included in this release, see the following sections.

Ad Intelligence Version 9

Updated the Version Number

The namespace has been changed to reflect the new version number of this release; otherwise, there are no updates to the Administration API. The new namespace name is https://bingads.microsoft.com/AdIntelligence/v9. For the production and sandbox endpoints, see Bing Ads Web Service Addresses.

Specifying Dates

The MonthAndYear object is removed, and all dates should be specified using the DayMonthAndYear object.

With the GetHistoricalSearchCount operation, EndMonthAndYear and StartMonthAndYear are replaced by EndTimePeriod and StartTimePeriod respectively.

The TimePeriodRollup element is added to the GetHistoricalSearchCount operation.

The HistoricalSearchCount object is removed, and instead you should use the HistoricSearchCountPeriodic object. For the KeywordSearchCount object, the data type of HistoricalSearchCounts should be an array of HistoricSearchCountPeriodic objects instead of an array of HistoricSearchCount.

Historical Data by Device

The GetHistoricalKeywordPerformanceByDevice and GetHistoricalSearchCountByDevice operations are removed, and instead you may use the corresponding GetHistoricalKeywordPerformance and GetHistoricalSearchCount operations.

The optional Devices element has been added to both GetHistoricalKeywordPerformance and GetHistoricalSearchCount operations. The Device element is added to the KeywordHistoricalPerformance and KeywordSearchCount objects returned by the corresponding operations.

The KeywordHistoricalPerformanceByDevice and KeywordSearchCountByDevice data objects are removed.

Historical Data by Match Type

You may specify multiple match types for keyword performance data requested with the GetHistoricalKeywordPerformance operation.

The MatchType element of the GetHistoricalKeywordPerformance request is replaced by MatchTypes. You may specify MatchTypes with an array of MatchType.

Keyword Estimates by Match Type

The following elements of the GetEstimatedBidByKeywords operation are updated.

  • The MatchTypes element is removed.

  • The data type of the Keywords element is updated to an array of KeywordAndMatchType objects instead of a string array.

Keyword Suggestions

The AdGroupId and CampaignId elements are added to the request message of the SuggestKeywordsFromExistingKeywords operation.

System_CAPS_ICON_note.jpg Note


These elements are not yet supported and may be used to influence keyword suggestions in a future release.

Entity Identifiers

The AdGroupId and CampaignId elements of both GetEstimatedBidByKeywords and GetEstimatedPositionByKeywords operations have updated data types from string to long.

Campaign Management Version 9

Editorial Reason

The data type of the Location element of the EditorialReason object is a string instead of an AdComponent value.

The AdComponent value set is removed.

Optimizer Version 9

Updated the Version Number

The namespace has been changed to reflect the new version number of this release; otherwise, there are no updates to the Administration API. The new namespace name is https://bingads.microsoft.com/Optimizer/v9. For the production and sandbox endpoints, see Bing Ads Web Service Addresses.

Apply Opportunities

The ApplyBudgetOpportunities operation is deprecated in Bing Ads API Version 8, and removed in Version 9. Instead you may use the ApplyOpportunities operation to apply opportunities of all types.

Budget Opportunity

The BudgetDepletionDate element of the BudgetOpportunity object is removed.

Error Codes

The ErrorCodes value set is removed. The data type of the Code element for BatchError and BatchError objects is updated from ErrorCodes to int.

Reporting Version 9

Updated the Version Number

The namespace has been changed to reflect the new version number of this release; otherwise, there are no updates to the Administration API. The new namespace name is https://bingads.microsoft.com/Reporting/v9. For the production and sandbox endpoints, see Bing Ads Web Service Addresses.

Language Codes

The combined LanguageAndRegion element is deprecated in Bing Ads API Version 8, and removed in Version 9. Instead you may use the respective LanguageCode and Country elements.

The LanguageAndRegionReportFilter object is removed.

The LanguageAndRegion element is removed from the following report filter data objects, and instead you may filter by language using the respective LanguageCode element.

The LanguageAndRegion value is removed from the following report columns.

Impression Share

The ImpressionLostToOthersPercent and ImpressionLostToRelevancePercent elements are deprecated in Bing Ads API Version 8, and removed in Version 9.

The ImpressionLostToOthersPercent and ImpressionLostToRelevancePercent values are removed from the following report columns.

Migration Reports

Bing Ads has transitioned away from multiple match types per keyword. The programming elements for migration reporting are removed in version 9.

The KeywordMigrationReportRequest data object and the KeywordMigrationReportColumn value set are removed.

Cashback

The Cashback feature is no longer supported.

The CashbackReportFilter is removed.

The Cashback element is removed from the DestinationUrlPerformanceReportFilter.

The Cashback value is removed from the KeywordPerformanceReportColumn report column.

Behavioral and User Segment Targeting

The behavioral and user segment targeting features are no longer supported.

The following data objects related to behavioral and segment targeting are removed.

  • BehavioralPerformanceReportFilter

  • BehavioralPerformanceReportRequest

  • BehavioralTargetReportFilter

  • BehavioralTargetReportRequest

  • SegmentationReportFilter

  • SegmentationReportRequest

The following value sets related to behavioral and segment targeting are removed.

  • BehavioralPerformanceReportColumn

  • BehavioralTargetReportColumn

  • SegmentationReportColumn

  • AgeGroupReportFilter

  • GenderReportFilter

Ad Group Report Scope

You may now specify individual ad groups for the AdExtensionByAdsReportRequest and AdExtensionByKeywordReportRequest.

The data type of their Scope element is updated from AccountThroughCampaignReportScope to AccountThroughAdGroupReportScope.

Call Detail Report

Remove the TimePeriod value from the CallDetailReportColumn value set.

Top Results Sorted by Report Column

You may get performance data and attributes sorted ascending or descending with the KeywordPerformanceReportRequest.

Within the KeywordPerformanceReportRequest object, set the MaxRows element to specify the top number of rows to return per aggregation period. The Sort element is a list of KeywordPerformanceReportSort objects, each of which specify the sort order and corresponding KeywordPerformanceReportColumn.

June 2013

For information about the changes to the Bing Ads services included in this release, see the following sections.

Bulk Version 9

Updated the Version Number

The namespace has been changed to reflect the new version number of this release; otherwise, there are no updates to the Administration API. The new namespace name is https://bingads.microsoft.com/CampaignManagement/v9. For the production and sandbox endpoints, see Bing Ads Web Service Addresses.

Bulk Upload

Support is added for uploading entity data in bulk.

Upload data in bulk using the following operations.

With the ResponseMode value set, you may specify whether the bulk service should return upload errors with their corresponding data.

Download Performance Data

You may specify whether to include performance data such as spend, with your entity data such as campaign settings.

For the following operation requests, the DataScope and PerformanceStatsDateRange elements are added.

Specify data scope with the DataScope value set.

Specify the date range for performance data with the PerformanceStatsDateRange data object. The start and end dates can be specified with the ReportTimePeriod value set.

Error Handling

The Type element is added to the BatchError object.

The EditorialError object is derived from the BatchError object, and is added to the Bulk service in version 9.

Downloading Entities

Support is added for more granular selection of entities to download.

For the following operation requests, the AdditionalEntities element is renamed Entities.

The AdditionalEntity value set is replaced by the BulkDownloadEntity value set.

Download File Type

Support for downloading data as comma separated value (Csv) and tab separated value (Tsv) file types is added in the DownloadFileType value set.

Campaign Management Version 9

Updated the Version Number

The namespace has been changed to reflect the new version number for this release. The new namespace name is https://bingads.microsoft.com/CampaignManagement/v9. For the production and sandbox endpoints, see Bing Ads Web Service Addresses.

Error Handling

The Type element is added to the BatchError object.

The EditorialError object is derived from the BatchError object, and the string value of the inherited Type element is EditorialError. Where the following elements were direct members of EditorialError in version 8, they are inherited from the BatchError object in version 9.

  • Code

  • ErrorCode

  • Index

  • Message

The Location and ReasonCode elements are added to the EditorialError object.

Ad Extensions

AdExtension2 has been renamed AdExtension, and retains the Id, Status, Type, and Version elements. The CampaignId, EnableLocationExtension, and PhoneExtension elements of the version 8 AdExtension are not available in version 9.

Ad Extension Association

In version 8, ad extensions can be associated with campaigns. In version 9, ad extensions may be associated with campaigns and ad groups.

Manage extensions associations with the following operations.

Manage extensions associations with the following data objects.

The AssociationFilter value set is replaced by the AssociationType value set, specifically when calling the GetAdExtensionIdsByAccountId operation.

Ad Extension Editorial

You may get the reasons why an ad extension with associated entity failed editorial review.

The GetAdExtensionsEditorialReasonsByCampaignIds operation is replaced by the GetAdExtensionsEditorialReasons operation.

The AdExtensionEditorialStatus value set represents the editorial status of an ad extension with an entity, and is surfaced in the new AdExtensionAssociation data object.

Device Preference

Bing Ads will offer enhanced campaign management features in . You will be able to specify whether you prefer to show text ads or ad extensions on mobile devices or all devices.

The DevicePreference element is added to the following data objects.

Forward Compatibility

To avoid otherwise breaking changes when new elements are added in future releases of Bing Ads API Version 9 , the ForwardCompatibilityMap element is added to the following objects.

Partial Success for Ads and Keywords

When adding, updating, or deleting ads or keywords in batches of one or more, the operation may succeed for some and fail for part of the batch.

The PartialErrors element is added to the response message for the following service operations.

The PartialErrors element represents an array of BatchError objects that contain details for any entities that were not successfully added, updated, or deleted.

If the BatchError objects are derived EditorialError objects, then the reason why the add or keyword failed editorial review will be included.

Pausing and Resuming Entities

You may pause and resume the following entities by setting or updating the respective status element.

Ad Rotation

Ad rotation is set within the Ad Group data object instead of using the GetAdRotationByAdGroupIds and SetAdRotationToAdGroups operations.

Publisher Countries

In version 8 the concept of publisher countries for an ad group was deprecated. With version 9 the PublisherCountries element is removed from the AdGroup object. To target your ads by location use location targeting, and otherwise your ads will be displayed to all eligible markets for your customer.

Keyword Bid Match Type

Bing Ads has transitioned from multiple match types per keyword. Each keyword may have one bid and one match type. This is already enforced in version 8, and the version 9 object model is updated to reflect the new paradigm.

For a given Keyword data object, all of the following elements replaced by both Bid and MatchType.

  • BroadMatchBid

  • ContentMatchBid

  • ExactMatchBid

  • PhraseMatchBid

The MatchType can be specified with the MatchType value set.

Bid Adjustment

Bing Ads is transitioning from incremental bid adjustments to multiplicative bid adjustments. Support will also be added for a wider range and more granular bid adjustments, for example negative 17 percent.

The IncrementalBid element is replaced by the BidAdjustment element in each of the target bid objects.

Keyword Destination Url

The keyword level destination URL is now included in the Keyword object instead of managing via the GetDestinationUrlByKeywordIds and SetDestinationUrlToKeywords operations.

Negative Keywords

Support for negative keywords within the Keyword data object was discontinued in version 8, and with version 9 theNegativeKeywords element was removed from the Keyword object.

Device OS Targeting

The device OS target can be managed in parity with other target types. An object named DeviceOSTarget exists in version 9, and its usage and elements have changed from version 8.

Targeting All Locations

The version 8 TargetAllLocations element is deprecated. In version 8 when TargetAllLocations is set to true, your ads participate in the auction for all locations. The service uses the base bid value for all locations that you did not target, and the incremental bid value for all locations that you did target. The default is false, whereby your ads participate in the auction only if the user is in all of the specified target locations. The service uses the incremental bid values of all specified targets in the auction.

In version 9 TargetAllLocations is removed and the behavior is identical to setting the version 8 TargetAllLocations element to false. To target all available countries and regions for your Bing Ads customer, do not create any location target. To target specific countries or regions, create individual targets for each city, country, metro area, radius, and state.

The TargetAllLocations element is removed from the LocationTarget object.

Location Exclusions

You may specify locations to exclude from a target within the corresponding location target bid.

To exclude a target set the IsExcluded element to true within any of the following target bids. The default is false.

Business Locations

Business locations contain addresses used by business location targeting and the version 8 AdExtension object. These are deprecated in version 8, and the corresponding objects and service operations are removed in version 9.

Legacy Targeting

The following operations were deprecated in version 8, and removed in version 9.

  • AddTarget

  • DeleteTarget

  • GetTargetByAdGroupId

  • UpdateTarget

Migration Status Info

Bing Ads has transitioned away from multiple match types per keyword. The programming elements for migration status information are removed in version 9.

Campaign Analytics

Programming elements for managing campaign analytics are removed.

Image and Media

The AddImage and GetImageById operations are deprecated in version 8 and removed in version 9.

Instead you may use AddMedia and GetMediaByIds respectively.

String Normalization

The GetNormalizedStrings operation has been removed.

Ad Components

The CashbackTextParam value of the AdComponent value set has been removed.

Community Additions

ADD
Show:
© 2016 Microsoft