Export (0) Print
Expand All

Release Notes

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

System_CLiX_important Important

Bing Ads will introduce some potentially breaking changes in Q3 2014. You should update your Campaign Management service proxy to get the latest web service references.

For more information about the upcoming changes, please see these sections below.

September 2014

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

Campaign Management

Targets

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

System_CLiX_note Note

Previously this feature was only available for pilot participants.

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 C# | Java | PHP.

Reporting

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

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

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_CLiX_important 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

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 MediaAssociation 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

Order By Field for Search Operations

The LifeCycleStatus value is added to the OrderByField value set.

System_CLiX_note Note

This value is reserved for future use.

Customer Management

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

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

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

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

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

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 data object.

Campaign Management

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.

System_CLiX_note Note

Currently this feature is only available in production for pilot participants, and will be generally available for all advertisers in Q3 2014. This feature is already available in sandbox for all advertisers.

System_CLiX_note 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_CLiX_note 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 C# | Java | PHP.

Targets

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

System_CLiX_note Note

Currently this feature is only available for pilot participants, and will be generally available for all advertisers in Q3 2014.

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 C# | Java | 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_CLiX_note 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 Data Object and RadiusTargetBid2 Data Object 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

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

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_CLiX_note 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_CLiX_note Note

If specified, the OpportunityModifiers overrides any specified OpportunityKeys.

Reporting

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

Insertion Order

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

Customer Management

Search Accounts

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

Reporting

Geo Location

The GeoLocationPerformanceReportRequest Data Object, GeoLocationPerformanceReportFilter Data Object, and GeoLocationPerformanceReportColumn Value Set are added.

System_CLiX_note Note

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

April 2014

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

Ad Intelligence

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

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

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.

System_CLiX_note Note

This will be available in an upcoming release of Bing Ads API Version 9, towards the end of Q2 2014.

Customer Management

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_CLiX_note 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.

System_CLiX_note Note

This will be available in an upcoming release of Bing Ads API Version 9, towards the end of Q2 2014.

Reporting

Entity Identifiers

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

Value Set

Columns Added

AccountPerformanceReportColumn

AccountId

AdDynamicTextPerformanceReportColumn

AccountId

AdGroupPerformanceReportColumn

AccountId

AdPerformanceReportColumn

AccountId

CampaignId

AgeGenderDemographicReportColumn

AccountId

AdGroupId

CampaignId

BudgetSummaryReportColumn

AccountId

CampaignId

CampaignPerformanceReportColumn

AccountId

DestinationUrlPerformanceReportColumn

AccountId

GeographicalLocationReportColumn

AccountId

AdGroupId

CampaignId

RichAdComponentPerformanceReportColumn

AccountId

SearchCampaignChangeHistoryReportColumn

AccountId

AdGroupId

CampaignId

March 2014

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

Bulk

Detailed Download Status

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

Campaign Management

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 Data Object 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 Data Object. 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

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 Data Object with an optional AdExtensionDetailReportFilter Data Object. Specify attribute and performance statistic columns with the AdExtensionDetailReportColumn Value Set. 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.

Attributes

Performance 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_CLiX_important 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

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_CLiX_note Note

The email address of the Microsoft Account may differ from the Email element of the ContactInfo Data Object.

Reporting

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 AdGroup 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

Detailed Download Status

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

System_CLiX_note 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

ActiveLimited Editorial Status

The ActiveLimited value is added to the following value sets.

System_CLiX_note Note

This will be available in an upcoming release of Bing Ads API Version 9, towards the end of Q2 2014.

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

Format Version

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

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.

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

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_CLiX_note 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

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_CLiX_note 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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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_CLiX_note 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

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

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 OperationError objects is updated from ErrorCodes to int.

Reporting

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 KeywordPerformanceReportFilter.

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

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

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 late Q3 2013. 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 AdGroup 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 Data Object 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:
© 2014 Microsoft