Migrate to Version 12

Important

Bing Ads API version 11 sunset date was October 31, 2018. Bing Ads API version 12 will sunset October 31, 2019. To view version 13 migration content, use the version selector near the table of contents at the top and left side of the page.

The sections below describe Bing Ads API changes from version 11 to version 12.

Authentication for All Services

Breaking Changes

Microsoft Account Authentication via OAuth is Required

Starting with Bing Ads API version 12, only OAuth authentication is supported via the AuthenticationToken header element. Managed credentials i.e., the UserName and Password header elements are not supported.

For more information on how to use OAuth with Microsoft Advertising, see Authentication with OAuth and Authentication With the SDKs.

Multi User Credentials

Previously one Microsoft Advertising user could only access accounts within a single customer. You could manage accounts across multiple customers as an agency, however, you would have had to create a distinct user per customer. Now with multi-user credentials it is possible to use one Microsoft account and manage accounts across different customers. Your Microsoft account can be assigned a different user role (Super Admin, Standard User, Advertiser Campaign Manager, or Viewer) per customer that you can access. For example, your multi-user credentials grants you access to Customer A and Customer B. However, your Viewer user role for Customer A limits you from making any changes on the accounts that Belong to Customer A. But as a Super Admin for Customer B, you have full control over that customer's accounts.

Please note the following changes from version 11 to 12 if you or one of your clients have setup Multi-User Credentials for Customer Accounts.

Starting with Bing Ads API Version 12 the multi-user credentials can access accounts across multiple customers. To switch context between customers you are required to set the CustomerId and CustomerAccountId header elements for Ad Insight, Bulk, Campaign Management, and Reporting services.

Note

The CustomerId and CustomerAccountId headers are not available for the Customer Billing and Customer Management services, because they automatically detect the customer context of the current authenticated user.

The merged credentials that could authenticate via Bing Ads API Version 11 will not authenticate via Bing Ads API Version 12.

Tip

To confirm availability, if the credentials no longer work via the Microsoft Advertising web application (due to being merged for multi-user credentials via another email address), then the merged Microsoft account could still authenticate via Bing Ads API Version 11 but cannot authenticate via Bing Ads API Version 12.

Ad Insight

For comprehensive version 12 service reference documentation see Ad Insight.

Breaking Changes

Proxy Client

Update your proxy client to use the new endpoint address and namespace.

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

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

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

Location Identifiers for Keyword Estimates

The list of PublisherCountries is replaced with a list of LocationIds for both the GetEstimatedBidByKeywords and GetEstimatedPositionByKeywords operations. This change enables you to get more accurate estimates by refining the requested locations e.g., city or metro area.

Keyword Idea Attributes

In version 12 all attributes within the KeywordIdea are nillable i.e., AdImpressionShare, Competition, Relevance, Source, and SuggestedBid. If you do not request them, the GetKeywordIdeas operation will return nil properties in the returned KeywordIdea. In addition the Competition KeywordIdeaAttribute is no longer required when calling GetKeywordIdeas.

In version 11 if you didn't request AdImpressionShare, Relevance, Source, or SuggestedBid the GetKeywordIdeas operation returned zero values (AdImpressionShare=0, Relevance=0, Source=Unknown, and SuggestedBid=0), although the values should not have been used.

ISO Currency Codes

The Currency value set is renamed as CurrencyCode. The values are updated with ISO codes e.g., USD replaces USDollar.

The new value set is used with the GetEstimatedBidByKeywords and GetEstimatedPositionByKeywords operations.

The new value set is used with the BidLandscapePoint, EstimatedBidAndTraffic, and EstimatedPositionAndTraffic objects.

Traditional Chinese

To specify Traditional Chinese in version 12 you must use TraditionalChinese (without space) when setting the Language element e.g., for the GetEstimatedBidByKeywords and GetEstimatedPositionByKeywords operations. Version 11 only supported Traditional Chinese (with space).

Keyword Demographic

The age range element names are updated within the KeywordDemographic object.

Version 11 Version 12
Age18_24 EighteenToTwentyFour
Age25_34 TwentyFiveToThirtyFour
Age35_49 ThirtyFiveToFourtyNine
Age50_64 FiftyToSixtyFour
Age65Plus SixtyFiveAndAbove

First Page Ad Position

In the AdPosition and TargetAdPosition value sets, SideBar is replaced with FirstPage.

Content Ad Distribution

The Content ad distribution is no longer supported in Microsoft Advertising, and the Content value is removed from the MatchType value set.

Bulk

For comprehensive version 12 service reference documentation see Bulk.

Breaking Changes

Proxy Client

Update your proxy client to use the new endpoint address and namespace.

The namespace is https://bingads.microsoft.com/CampaignManagement/v12.

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

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

Format Version 6.0

Support for Bulk file format version 5.0 is removed. Bing Ads API Version 12 only supports format version 6.0. When calling the DownloadCampaignsByAccountIds and DownloadCampaignsByCampaignIds operations you must specify 6.0 in the FormatVersion request element. When uploading a bulk file, you must specify 6.0 in the Name field of the Format Version record. Changes to records between format version 5.0 and 6.0 are described in more detail in the following sections.

Sitelink Ad Extensions

During calendar year 2017, Microsoft Advertising upgraded all format version 5.0 Sitelink Ad Extension records (contains multiple sitelinks per ad extension) to Sitelink2 Ad Extension objects (contains one sitelink per ad extension).

In Bing Ads API Version 12 the format version 5.0 Sitelink Ad Extension, Campaign Sitelink Ad Extension, and AdGroup Sitelink Ad Extension records are removed. Likewise, the SiteLinksAdExtension, CampaignSiteLinksAdExtensions, and AdGroupSiteLinksAdExtensions values are removed from the DownloadEntity value set.

When you migrate to version 12 remove the '2' suffix from all Sitelink2 records i.e., use the format version 6.0 Sitelink Ad Extension, Account Sitelink Ad Extension, Campaign Sitelink Ad Extension, and Ad Group Sitelink Ad Extension records. Likewise remove the '2' suffix from each DownloadEntity value in version 12 i.e., use SitelinkAdExtensions, AccountSitelinkAdExtensions, CampaignSitelinkAdExtensions, and AdGroupSitelinkAdExtensions.

Shopping Campaign Sub Type

We are introducing Cooperative campaigns during calendar year 2018 as a sub type of Microsoft Shopping Campaigns. More details about Cooperative campaigns are coming soon, and in the meantime please note the potential required changes in Bing Ads API Version 12 for your application to support existing Microsoft Shopping Campaigns. Whether or not you plan to adopt Cooperative campaigns, you might need to make code changes if your application supports any shopping campaigns.

When you download campaigns by including Campaigns from the DownloadEntity value set, please check the Campaign Type and Sub Type fields of each Campaign. If the Campaign Type field is set to Shopping then you must also check the value of the Sub Type field. If the Sub Type field is empty then it is a standard Microsoft Shopping campaign. If the value is set to ShoppingCoOperative, the campaign is a Cooperative campaign.

Entity Performance Data

Bulk download of performance data is no longer supported. The EntityPerformanceData value of the DataScope value set is no longer supported in Bing Ads API Version 12, and will be removed from the service contract in a future version. If you want data aggregated by day, week, or month, you can use the Reporting API. For more details see Reports.

Audience Targeting Setting

The Remarketing Targeting Setting field of an Ad Group is removed.

To determine whether the audience association is bid only or target and bid, use the Target Setting field of an Ad Group. The setting is applicable for all audiences associated with the ad group, including but not limited to remarketing lists.

In version 11 to set the "target and bid" option you would have set the Remarketing Targeting Setting field to TargetAndBid. To set the "target and bid" option in version 12, include the Audience value in the new Target Setting field.

In version 11 to set the "bid only" option you would have set the Remarketing Targeting Setting field to BidOnly. To set the "bid only" option in version 12, exclude the Audience value from the new Target Setting field. To update from "target and bid" to "bid only" you'll need to explicitly remove the "target and bid" option e.g., set the Target Setting field to "delete_value". For more details please see Target Setting.

Expanded Text Ad Domain

The Display Url field of an Expanded Text Ad record is renamed as Domain.

Content Ad Distribution

The Content ad distribution is no longer supported in Microsoft Advertising, and the Content Bid, Content Network, and Search Network fields of an Ad Group are removed from version 12. The ad distribution is effectively determined by the campaign type e.g., Search or Audience campaigns. The Search Bid field of an Ad Group is renamed Cpc Bid.

The Campaign Type value of the corresponding Campaign is updated from SearchAndContent to Search. Likewise instead of SearchAndContent use Search in the Supported Campaign Types column of the Custom Audience, In Market Audience, and Remarketing List records.

Cpm Pricing Model

The CPM pricing model is no longer supported in Microsoft Advertising, and the Pricing Model field of an Ad Group is removed from version 12. The Pricing Model field in version 11 was optional, defaulted to Cpc, and could only be set to Cpc.

Time Zone Updates

The following time zone values are updated for the Time Zone field of the Campaign record.

  • The value for the UTC+12 time zone is updated from MagadanSolomonIslandNewCaledonia to SolomonIslandNewCaledonia.
  • The value is updated from Almaty_Novosibirsk to AlmatyNovosibirsk.
  • The value is updated from MidwayIslandand_Samoa to MidwayIslandAndSamoa.
  • The value is updated from MountainTime_US_Canada to MountainTimeUSCanada.

In-Market Audiences Supported for Audience Campaigns

In version 12 the AudienceNetworkInMarketAudiences and AudienceNetworkAudiences values are removed from the DownloadEntity value set. In version 12 when you request in-market audiences via the InMarketAudiences or Audiences DownloadEntity values, all of them will be returned. In version 11 the in-market audiences that are supported for Audience campaigns were not returned unless you included AudienceNetworkInMarketAudiences or AudienceNetworkAudiences in the download request.

Note

In both version 11 and 12 the Supported Campaign Types column is available with each Custom Audience, In Market Audience, and Remarketing List record. You should first verify that the audience is supported for your campaign type before using it.

Error Code for InMarketAudienceCouldNotBeDeleted

In-market audiences cannot be deleted in both version 11 and version 12. Custom audiences can be deleted in both version 11 and 12. The error code CustomAudienceAndInMarketAudienceCouldNotBeDeleted (4860) that was returned in version 11 is replaced by error code InMarketAudienceCouldNotBeDeleted (4864) in version 12.

Audience Ads Bid Adjustment

Instead of setting the Ad Format Preference of an expanded text ad to Native, you must set it to Audience Ad.

Campaign and Ad Group Names for Audience and Ad Extension Associations

The Campaign and Ad Group names are no longer included when you download audience and ad extension association records.

Campaign Management

For comprehensive version 12 service reference documentation see Campaign Management.

Breaking Changes

Proxy Client

Update your proxy client to use the new endpoint address and namespace.

The namespace is https://bingads.microsoft.com/CampaignManagement/v12.

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

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

Data Contract Namespace

The data contract namespace in version 11 referenced the AdCenter namespace.

For clients who encode the SOAP envelope in version 12 e.g. PHP clients who encode a SoapVar for Webpage, you'll need to update from http://schemas.datacontract.org/2004/07/Microsoft.AdCenter.Advertiser.CampaignManagement.Api.DataContracts.V11 to the Campaign Management Version 12 target namespace i.e., https://bingads.microsoft.com/CampaignManagement/v12.

Bing Ads Python SDK clients will need to update several namespace prefixes for the SUDS client factory objects e.g., if you used ns0:CustomParameter in Bing Ads API Version 11 you'll use CustomParameter (without the 'ns0' prefix) in version 12. See Using SUDS for details about how to determine the namespace prefix.

Return Additional Fields

The ReturnAdditionalFields element is removed from the GetAdGroupsByCampaignId,GetAdGroupsByIds, GetAudiencesByIds, GetKeywordsByAdGroupId, GetKeywordsByEditorialStatus, and GetKeywordsByIds request messages, and the corresponding elements of each AdGroup, Audience, and Keyword are returned by default.

Sitelink Ad Extensions

During calendar year 2017, Microsoft Advertising upgraded all version 11 SiteLinksAdExtension objects (contains multiple sitelinks per ad extension) to Sitelink2AdExtension objects (contains one sitelink per ad extension).

In Bing Ads API Version 12 the SiteLinksAdExtension and SiteLink objects are removed. The Sitelink2AdExtension object is renamed SitelinkAdExtension. Likewise, the SiteLinksAdExtension value is removed from AdExtensionsTypeFilter value set, and the Sitelink2AdExtension value is renamed Sitelink2AdExtension (sans '2' suffix).

When you migrate to version 12 remove the '2' suffix from Sitelink2AdExtension, and otherwise the version 12 SitelinkAdExtension interface is identical to the version 11 Sitelink2AdExtension object. Likewise the ad extension Type value is SitelinkAdExtension when you retrieve a sitelink ad extension in version 12.

Shopping Campaign Sub Type

We are introducing Cooperative campaigns during calendar year 2018 as a sub type of Microsoft Shopping Campaigns. More details about Cooperative campaigns are coming soon, and in the meantime please note the potential required changes in Bing Ads API Version 12 for your application to support existing Microsoft Shopping Campaigns. Whether or not you plan to adopt Cooperative campaigns, you might need to make code changes if your application supports any shopping campaigns.

When you call GetCampaignsByAccountId or GetCampaignsByIds and the CampaignType is set to Shopping, please check the SubType of each Campaign. If the SubType is not set then it is a standard Microsoft Shopping campaign. If the value is set to ShoppingCoOperative, the campaign is a Cooperative campaign.

In Bing Ads API Version 11 with the GetCampaignsByAccountId and GetCampaignsByIds operations you were required to set the ReturnCoOpCampaigns request element to retrieve Cooperative campaigns. In Bing Ads API Version 12 the request element is removed and all campaigns are returned by default.

In Bing Ads API Version 11 with the GetAdGroupsByCampaignId and GetAdGroupsByIds operations you were required to set the ReturnCoOpAdGroups request element to retrieve ad groups of Cooperative campaigns. In Bing Ads API Version 12 the request element is removed and all campaigns are returned by default.

In Bing Ads API Version 11 with the GetBMCStoresByCustomerId operation you were required to set the ReturnCoOpStores request element to retrieve BMCStore objects that support Cooperative campaigns. In Bing Ads API Version 12 the request element is removed and all BMCStore objects are returned by default.

Audience Targeting Setting

The RemarketingTargetingSetting element of an AdGroup is removed.

To determine whether the audience association is bid only or target and bid, use the TargetSetting object via the Settings element of an AdGroup. The setting is applicable for all audiences associated with the ad group, including but not limited to remarketing lists.

Account Migration Status Info

The MigrationStatusInfo (singular) element of an AccountMigrationStatusesInfo object is renamed as MigrationStatusInfos (plural). This will resolve ambiguity between the returned name and data type.

Expanded Text Ad Domain

The DisplayUrl element of an ExpandedTextAd object is renamed as Domain.

Media Type

The name, values, and business rules of the MediaType and Type elements of a Media object are swapped. In version 11 the derived media type of an Image was returned in the MediaType element e.g., Image, and the aspect ratio was returned in the Type element e.g., Image15x10. In version 12 the derived media type of an Image is returned in the Type element e.g., Image, and the aspect ratio is returned in the MediaType element e.g., Image15x10. Long term this should reduce friction for clients who depend on the derived type in the Type element.

Likewise the name, values, and business rules of the MediaType and Type elements of a MediaMetaData object are swapped.

Location Ad Extension Media

Icons and images for location ad extensions were reserved for internal use in version 11. In version 12, the IconMediaId and ImageMediaId elements are removed from the LocationAdExtension object, and the GetMediaByIds operation is removed.

Content Ad Distribution

The Content ad distribution is no longer supported in Microsoft Advertising, so the AdDistribution and ContentBid elements of an AdGroup are removed from version 12. The ad distribution is effectively determined by the campaign type e.g., Search or Audience campaigns. The SearchBid element of an AdGroup is renamed CpcBid.

The CampaignType value is updated from SearchAndContent to Search, and the Content value is removed from the MatchType value set. Likewise instead of SearchAndContent use Search in the SupportedCampaignTypes element of the CustomAudience, InMarketAudience, and RemarketingList objects.

Cpm Pricing Model

The CPM pricing model is no longer supported in Microsoft Advertising, and the PricingModel element of an AdGroup is removed from version 12. The PricingModel element in version 11 was optional, defaulted to Cpc, and could only be set to Cpc.

Time Zone Updates

The following time zone values are updated for the TimeZone element of the Campaign object.

  • The value for the UTC+12 time zone is updated from MagadanSolomonIslandNewCaledonia to SolomonIslandNewCaledonia.
  • The value is updated from Almaty_Novosibirsk to AlmatyNovosibirsk.
  • The value is updated from MidwayIslandand_Samoa to MidwayIslandAndSamoa.
  • The value is updated from MountainTime_US_Canada to MountainTimeUSCanada.

Batch Error Collection Editorial Errors

The Appealable, DisapprovedText, Location, PublisherCountry, and ReasonCode elements are removed from the the ForwardCompatibilityMap of the BatchErrorCollection object, and added to the new EditorialErrorCollection object.

Age Range Values

The ZeroToSeventeen and ThirteenToSeventeen values are removed from the AgeRange value set. These values were not ever supported.

In-Market Audiences Supported for Audience Campaigns

In version 12 the ReturnSupportedCampaignTypes request element is removed from GetAudiencesByIds. Now when you request in-market audiences, all of them will be returned and will include the SupportedCampaignTypes element in each Audience object by default. In version 11 the in-market audiences that are supported for Audience campaigns were not returned unless you set ReturnSupportedCampaignTypes true. Effectively the ReturnSupportedCampaignTypes element in GetAudiencesByIds version 11 gated both the SupportedCampaignTypes element for all audience types, as well as the in-market audiences that are supported for Audience campaigns.

Note

In both version 11 and 12 the SupportedCampaignTypes field is available with each CustomAudience, InMarketAudience, and RemarketingList object. You should first verify that the audience is supported for your campaign type before using it.

Error Code for InMarketAudienceCouldNotBeDeleted

In-market audiences cannot be deleted in both version 11 and version 12. Custom audiences can be deleted in both version 11 and 12. The error code CustomAudienceAndInMarketAudienceCouldNotBeDeleted (4860) that is still returned in version 11 is replaced by error code InMarketAudienceCouldNotBeDeleted (4864) in version 12.

Error Codes for Maximum Audiences

The maximum audience limits for customer and account level apply to all audience types i.e., not only remarketing lists. Therefore MaxRemarketingListsPerCustomerLimitReached (4833) is replaced by MaxAudiencesPerCustomerLimitReached (4866). MaxAudiencesPerAccountLimitReached (4865) is available in both version 11 and 12 for the account level audience limit.

Error Codes for Entity Settings

The error code string for code 1149 is updated from CampaignServiceDuplicateSettingsInCampaign to CampaignServiceDuplicateSettingsInEntity. The same error code can be returned whether the duplicate settings are at campaign or ad group level. For example if you attempt to set duplicate ShoppingSetting objects in a campaign or duplicate TargetSetting objects in an ad group.

The error code string for code 1151 is updated from CampaignServiceCampaignSettingsNotAllowed to CampaignServiceInvalidSettingForCampaignType. The same error code can be returned whether the settings are at campaign or ad group level. For example if you attempt to apply a shopping setting in a Dynamic Search Ads campaign.

Audience Ads Bid Adjustment

The NativeBidAdjustment property is renamed as AudienceAdsBidAdjustment in the AdGroup and Campaign objects.

Instead of setting the AdFormatPreference of an expanded text ad to Native, you must set it to AudienceAd.

New Features

Inherited Bid Strategy Types

The InheritedBidStrategyTypes element is added to the response message of the AddKeywords and UpdateKeywords operations.

Each string in the list is returned in the same order and corresponds to the keywords in the request message. The value of each string represents the type of bidding scheme (a.k.a. bid strategy type) that is inherited from the parent campaign or ad group. This element is not returned by default. You must set ReturnInheritedBidStrategyTypes true in the request.

Customer Billing

For comprehensive version 12 service reference documentation see Customer Billing.

Breaking Changes

Proxy Client

Update your proxy client to use the new endpoint address and namespace.

The namespace is https://bingads.microsoft.com/Billing/v12.

The production endpoint is https://clientcenter.api.bingads.microsoft.com/Api/Billing/v12/CustomerBillingService.svc.

GetBillingDocuments by BillingDocumentInfo

In version 12 a structured list of BillingDocumentInfo replaces the DocumentIds element in the GetBillingDocuments request. Now you can first call GetBillingDocumentsInfo and pass the results (up to 25 items) in the GetBillingDocuments request.

The CustomerId element is added to the BillingDocumentInfo object. When you call the GetBillingDocuments operation, both the CustomerId and DocumentId are required.

InsertionOrderStatus

The Pending and PendingSystemReview values are removed from the InsertionOrderStatus value set. The NotStarted value replaces Pending.

New Features

Insertion Order Pending Changes

In version 12 you can update you can update the comment, end date, name, notification threshold, purchase order, spend cap amount, and start date of insertion orders. Previously in version 11 you could only update the status of an InsertionOrder to approve or decline an insertion order that was not yet approved and active.

Before the insertion order becomes approved i.e., if the InsertionOrder status is set to PendingUserReview, you can make updates via the InsertionOrder object. Once the InsertionOrder status is Active, Exhausted, Expired, or NotStarted, then you can either make new changes or approve or decline the current pending changes via the InsertionOrderPendingChanges object. You can discover pending changes via SearchInsertionOrders, and then call UpdateInsertionOrder to change the status or update the insertion order settings. If the InsertionOrder status is Canceled or Declined then you cannot update the insertion order.

In version 11 you could find out if pending changes were available via the ChangePendingReview element of an insertion order. The PendingChanges element replaces it. Also note that the InsertionOrderId was renamed as Id for consistency with other objects.

Customer Management

For comprehensive version 12 service reference documentation see Customer Management.

Breaking Changes

Proxy Client

Update your proxy client to use the new endpoint address and namespace.

The namespace is https://bingads.microsoft.com/Customer/v12.

The production endpoint is https://clientcenter.api.bingads.microsoft.com/Api/CustomerManagement/v12/CustomerManagementService.svc.

The sandbox endpoint is https://clientcenter.api.sandbox.bingads.microsoft.com/Api/CustomerManagement/v12/CustomerManagementService.svc.

Multi User Credentials

With multi-user credentials, one email address can be associated with multiple roles i.e., one role for each customer they can access. Whether or not you have "multi-user" credentials, the Customer Management API maps your credentials via a single User object, with some notable changes to the returned user roles.

The Accounts, Customers, and Roles elements of the GetUser response are replaced with a list of CustomerRole objects named CustomerRoles.

In the response message for GetUser in version 11, the returned role or roles were applicable for all accounts or customers listed. You will only see the role(s) that the user had before multi-user credentials consolidation.

<Roles d4p1:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
  <a1:int>ValueHere</a1:int>
</Roles>
<Accounts d4p1:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
  <a1:long>ValueHere</a1:long>
</Accounts>
<Customers d4p1:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
  <a1:long>ValueHere</a1:long>
</Customers>

In the response message for GetUser in version 12, each returned role is mapped to a specific customer (and specific accounts if applicable). You can see the roles for all customers that the user can access before and after multi-user credentials consolidation.

<CustomerRoles xmlns:e328="https://bingads.microsoft.com/Customer/v12/Entities" d4p1:nil="false" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
  <e328:CustomerRole>
    <e328:RoleId>ValueHere</e328:RoleId>
    <e328:CustomerId>ValueHere</e328:CustomerId>
    <e328:AccountIds d4p1:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <a1:long>ValueHere</a1:long>
    </e328:AccountIds>
  </e328:CustomerRole>
</CustomerRoles>

Let's consider the following user roles and permissions before multi-user consolidation. Each user must log in separately and has different permissions during each logged in session. Likewise via the API each user's access token (see Authentication with OAuth) represents permissions limited to the corresponding user and role.

User Role Permissions
one@contoso.com Viewer Customer A - All Accounts
two@contoso.com Super Admin Customer B - All Accounts
three@contoso.com Viewer Customer C - Account A
four@contoso.com Standard User Customer B - All Accounts

First please note that only one email address per customer can be consolidated, so in this example two@contoso.com and four@contoso.com cannot be consolidated together. Now let's see what happens after the top three users are consolidated under one@contoso.com.

  • No changes for user four@contoso.com whether via the Microsoft Advertising web application, Microsoft Advertising Editor, or API.
  • The user one@contoso.com can log in via the Microsoft Advertising web application and Microsoft Advertising Editor. The consolidated users i.e., two@contoso.com and three@contoso.com no longer have permissions to sign in via the Microsoft Advertising web application or Microsoft Advertising Editor. While signed in as one@contoso.com, you can switch context to the customer accounts with corresponding user roles that had previously been assigned to two@contoso.com and three@contoso.com. Although you can access multiple customers signed in with one user's credentials (one@contoso.com), you will need to switch from customer to customer to manage the accounts that are linked with unique user roles. Customers and their related accounts remain distinct. For more details see the Microsoft Advertising help topic Managing your user name to access multiple accounts.
  • With Bing Ads API version 11 there is no change to access before versus after multi-user consolidation. Each of the user's access token (see Authentication with OAuth) represents permissions limited to the corresponding user and role.
  • Starting with Bing Ads API version 12, the access token for user one@contoso.com will represent permissions to the consolidated list (superset) of accounts. The user role in effect will depend on the customer and account identifiers specified in the service request. Access tokens for two@contoso.com and three@contoso.com will no longer be accepted.
  • The UserName returned via GetUser and GetUsersInfo will differ between version 11 and 12 for two@contoso.com and three@contoso.com. In version 11 the UserName will be two@contoso.com and three@contoso.com, whereas in version 12 the UserName for each of the corresponding user identifiers will be one@contoso.com. In other words the operations will always return whatever user name can authenticate using the respective API version.

    Note

    If the multi-user credentials were provisioned through the user invitation work flow i.e., there was never an "old user name" for access to a customer, a system generated GUID will be returned in the UserName element in version 11. In version 12 the multi-user email address will be returned.

Also of note is that the Name, Lcid, JobTitle, and ContactInfo user settings for the same person will be automatically synchronized with any updates that occur after user consolidation. The LastModifiedByUserId and LastModifiedTime are also in sync across each returned User object, unless you had an old username merged and have not updated any user settings since the consolidation.

Note

The TimeStamp differs from the LastModifiedTime. All TimeStamp values are unique per User and when you call UpdateUser you must include the corresponding user's timestamps (including the address timestamp).

For example let's say you haven't updated user information for one@contoso.com since prior to consolidation with two@contoso.com and three@contoso.com. After consolidation and until the user settings are updated post-consolidation, you will continue to observe a distinct LastModifiedByUserId and LastModifiedTime within each returned User object.

User Id Contact Info Id Permissions LastModifiedByUserId
123 234 Customer A - All Accounts 123
456 567 Customer B - All Accounts 456
789 890 Customer C - Account A 789

Now let's say that one@contoso.com is acting in the context of Customer B and updates their contact information. The updated contact information as well as the same LastModifiedByUserId and LastModifiedTime are now syncrhonized across all returned User objects.

User Id Contact Info Id Permissions LastModifiedByUserId
123 234 Customer A - All Accounts 456
456 567 Customer B - All Accounts 456
789 890 Customer C - Account A 456

User Roles

The UserRole value set is removed to ensure consistent mapping and forward compatibility for potential new user roles. In turn, the Role element of the UserInvitation object is replaced with an int value i.e., an element named RoleId.

MSA Migration Status for a User

The IsMigratedToMicrosoftAccount element is removed from the User object, since version 12 only supports Microsoft Acccount Authentication with OAuth.

Advertiser Account

The AdvertiserAccount object no longer derives from an Account base. The Account object is removed and its properties are moved directly to the AdvertiserAccount object.

Also because only one account type is supported, the AccountType and ApplicationType value sets are removed. In turn the AccountType element is removed from the AdvertiserAccount object, the CustomerAppScope element is removed from the User object, and the ApplicationScope request element is removed from the FindAccounts, FindAccountsOrCustomersInfo, GetCustomersInfo, and SignupCustomer operations.

Business Address

The BusinessName element is added to the Address object. It is required for BusinessAddress of each AdvertiserAccount, and ignored if you set it with the User address.

AutoTag Type

The AutoTag key and value pair is removed from the ForwardCompatibilityMap element of the AdvertiserAccount object. Instead the AutoTagType element is added to the AdvertiserAccount. The new AutoTagType values are Inactive, Preserve, and Replace. If you used values 0, 1, or 2 in the version 11 AutoTag, then you can replace them with the version 12 auto tag type as follows.

Version 11 Version 12
0 Inactive
1 Preserve
2 Replace

Tracking Url Template

The TrackingUrlTemplate key and value pair is removed from the ForwardCompatibilityMap element of the AdvertiserAccount object. Instead you can set the AccountProperty name for TrackingUrlTemplate via the Campaign Management service, or set the Tracking Template field of the Account record via the Bulk service.

ISO Currency Codes

The CurrencyType value set is renamed as CurrencyCode. The values are updated with ISO codes e.g., USD replaces USDollar. The new value set is used with the AdvertiserAccount object.

Time Zone Updates

The following values are updated in the TimeZoneType value set.

  • The value for the UTC+12 time zone is updated from MagadanSolomonIslandNewCaledonia to SolomonIslandNewCaledonia.
  • The value of InternationalDatelineWest (lowercase 'l' in Dateline) is updated to InternationalDateLineWest (uppercase 'L' in DateLine).

Search Customers Predicates

The following Predicate field and operator sets are no longer available in version 12.

  • PersonName Equals
  • PersonName Contains
  • Email Equals
  • Email Contains
  • UserName Contains (UserName Equals is still available in version 12)

Reporting

For comprehensive version 12 service reference documentation see Reporting.

Breaking Changes

Proxy Client

Update your proxy client to use the new endpoint address and namespace.

The namespace is https://bingads.microsoft.com/Reporting/v12.

The production endpoint is https://reporting.api.bingads.microsoft.com/Api/Advertiser/Reporting/v12/ReportingService.svc.

The sandbox endpoint is https://reporting.api.sandbox.bingads.microsoft.com/Api/Advertiser/Reporting/v12/ReportingService.svc.

Consistency Between WSDL Contract and Downloaded Report Columns

Previously there were some discrepancies between the report column value set names and the names of the columns in the downloaded reports. In Reporting API Version 12 all of the downloaded column names match the requested value. For example now when you submit a KeywordPerformanceReportRequest with the BidStrategyType value from the KeywordPerformanceReportColumn value set, the column name in the downloaded report is also BidStrategyType in Reporting API Version 12. Previously in version 11, the column name in the downloaded report was Bid strategy type.

The following column names have changed in the downloaded reports from version 11 to 12.

Version 11 Version 12
AudienceTargetSetting TargetingSetting
AutoTarget DynamicAdTarget
AutoTargetId DynamicAdTargetId
AutoTargetStatus DynamicAdTargetStatus
AvgCPP AverageCpp
BenchmarkCTR BenchmarkCtr
Bid strategy type BidStrategyType
CallDuration Duration
CallEndTime EndTime
CallStartTime StartTime
CallStatusName CallStatus
ClickSharePct ClickSharePercent
ClickTypeID ClickTypeId
CountryOrRegion Country
Device type DeviceType
DSAFinalURL FinalUrl
FinalAppURL FinalAppUrl
FinalMobileURL FinalMobileUrl
FinalURL FinalUrl
FirstLevelCategory Category1
Localstorecode LocalStoreCode
NegativeKeywordListName NegativeKeywordList
NegativeKeywordMatchTypeDesc NegativeKeywordMatchType
NodeId AdGroupCriterionId
ProductPartitionType PartitionType
PTR Ptr
Search query SearchQuery
SecondLevelCategory Category2
Status CampaignStatus
TopLevelCategory Category0

Likewise when you include the TimePeriod column in version 12 the name of the column in the downloaded report will be TimePeriod. In version 11 the column name varied by aggregation as follows.

Aggregation Version 11 Column Name Version 12 Column Name
Daily GregorianDate TimePeriod
DayOfWeek DayOfWeek TimePeriod
Hourly Hour, GregorianDate TimePeriod
HourOfDay HourOfDay TimePeriod
Monthly MonthStartDate TimePeriod
Weekly WeekStartDate TimePeriod
Yearly Year TimePeriod

Whereas in version 11 the time period for Hourly aggregation was split across two columns, in version 12 it will be formatted in the TimePeriod column with the date and hour (int value) delimited by a single pipe i.e., "mm/dd/yyyy 12:00:00 AM|hour" where 12:00:00 AM can be ignored. For example, if the click occurred March 15, 2018 between 07:00 and 08:00, then the field in the downloaded report would be "3/15/2018 12:00:00 AM|7". For more details see ReportAggregation and TimePeriod Column.

Column Restrictions

For some reports you cannot include constrained attributes in the same report request. For example when submitting the AccountPerformanceReportRequest and AdGroupPerformanceReportRequest if you include any of the impression share performance statistics columns, then you must exclude the BidMatchType, DeviceOS, and TopVsOther attribute columns. Likewise, if you include any of these attribute columns, then you must exclude all of the impression share performance statistics columns.

Starting with Bing Ads API Version 12, an error will be returned if you include any constrained report column combinations. Using Bing Ads API Version 11 the report submission did not fail; however, the fields returned in the downloaded report would be 0 (zero) in place of any meaningful data.

For more details, see Column Restrictions in Reports.

Report Aggregation

For parity with aggregation options (unit of time) in the Microsoft Advertising web application, Bing Ads API Version 12 enables comparable time periods that previously were not supported via Bing Ads API Version 11. The NonHourlyReportAggregation and SearchQueryReportAggregation value sets are removed, and you should use ReportAggregation values for all reports.

When submitting the following report requests, you must use the ReportAggregation data type instead of NonHourlyReportAggregation within the ReportAggregation element. Although the ReportAggregation value set includes additional aggregation periods, unless otherwise noted below these reports are still limited to Summary, Daily, Weekly, Monthly, and Yearly aggregation. If you submit a report with an invalid aggregation period, the API will return error code 2007, ReportingServiceInvalidReportAggregation.

Report Request Aggregation Periods Added in Version 12
AdDynamicTextPerformanceReportRequest Hourly
AdPerformanceReportRequest DayOfWeek, Hourly, HourOfDay
AgeGenderDemographicReportRequest None
ConversionPerformanceReportRequest None
DestinationUrlPerformanceReportRequest DayOfWeek, Hourly, HourOfDay
DSAAutoTargetPerformanceReportRequest DayOfWeek, Hourly, HourOfDay
DSACategoryPerformanceReportRequest DayOfWeek, Hourly, HourOfDay
GeographicPerformanceReportRequest DayOfWeek, Hourly, HourOfDay
GoalsAndFunnelsReportRequest None
PublisherUsagePerformanceReportRequest DayOfWeek, Hourly, HourOfDay
ShareOfVoiceReportRequest None
UserLocationPerformanceReportRequest DayOfWeek, Hourly, HourOfDay

When submitting the following report requests, you must use the ReportAggregation data type instead of SearchQueryReportAggregation within the ReportAggregation element.

Budget Summary Report Time

For parity with the predefined time options (e.g., 'Yesterday') for the budget summary report in the Microsoft Advertising web application, Bing Ads API Version 12 enables comparable predefined time options that previously were not supported via Bing Ads API Version 11. In version 11 only Today, Yesterday, LastSevenDays, ThisMonth, and LastMonth were supported for the budget summary report. Version 12 now supports Last14Days, Last30Days, LastFourWeeks, LastMonth, LastSevenDays, LastSixMonths, LastThreeMonths, LastWeek, LastYear, ThisMonth, ThisWeek, ThisYear, Today, and Yesterday.

The BudgetSummaryReportTimePeriod object is removed in version 12. When submitting a budget summary report request, you must use the ReportTimePeriod data type instead of BudgetSummaryReportTimePeriod within the PredefinedTime element of the BudgetSummaryReportTime object.

First Page Ad Position

In the KeywordPerformanceReportColumn value set SidebarBid is replaced with FirstPageBid. Based on your campaign performance and marketplace dynamics, this estimate is the bid amount that Microsoft Advertising calculates for your ad to be placed on the first page in the search results. The first page bid estimate is automatically generated by Microsoft Advertising as a reference, and is not a guarantee of ad position.

Content Ad Distribution

The Content ad distribution is no longer supported in Microsoft Advertising, and the Content value is removed from the AdDistributionReportFilter, BidMatchTypeReportFilter, and DeliveredMatchTypeReportFilter value sets.

Audience Ads Distribution

The Native value is renamed Audience in the AdDistributionReportFilter value set.

Historical Columns

The AdGroupPerformanceReportColumn, CampaignPerformanceReportColumn, and KeywordPerformanceReportColumn values are renamed from Historic to Historical.

Version 11 Version 12
HistoricQualityScore HistoricalQualityScore
HistoricExpectedCtr HistoricalExpectedCtr
HistoricAdRelevance HistoricalAdRelevance
HistoricLandingPageExperience HistoricalLandingPageExperience

In addition, the 2054 error code is renamed from InvalidGrainForHistoricQualityScoreColumns to InvalidGrainForHistoricalQualityScoreColumns.

Internal Columns

The BusinessCategoryId, BusinessCategoryName, BusinessListingId, and BusinessListingName values are removed from the AdPerformanceReportColumn, AdGroupPerformanceReportColumn, and KeywordPerformanceReportColumn value sets. These columns were previously only available for internal use.

New Features

Report Time Zone

Bing Ads API version 12 now lets you choose a ReportTimeZone when you submit a ReportRequest via the BudgetSummaryReportTime or ReportTime objects. The time zone can help you accurately scope data for the selected date range.

More Flexible Report Time Periods

Bing Ads API version 12 now lets you choose LastFourteenDays and LastThirtyDays from the ReportTimePeriod value set when you submit a report request.