This article contains answers to some frequently asked questions about the Bing Ads API.
Where can I get help?
The Microsoft Q&A forum is available for the developer community to ask and answer questions about the Bing Ads APIs and Microsoft Advertising Scripts. Microsoft monitors the forums and replies to questions that the community has not yet answered.
To make sure that we see your question, tag it with 'advertising-api'.
If the investigation involves sensitive account or personal details, or if you are not finding the information you need to solve your problem via Microsoft Q&A, please contact Microsoft Advertising Support. To resolve the issue efficiently, please provide support with the details requested in Engaging Support.
How can I find out about changes?
The Release Notes and Migration Guide are great resources to start with.
You can sign up for the monthly newsletter via the News tab of the Developer Portal, and that's also where the latest blog announcements are aggregated.
What are the requirements to use the Bing Ads API?
To get started, you need to sign up for a Microsoft Advertising account, and then get your developer token at via the Account tab of the Developer Portal.
Which programming languages and SDKs are supported?
You can develop Bing Ads API applications with any programming language that supports web services. The Bing Ads API Software Development Kits (SDK) enhance the experience of developing Bing Ads API applications with .NET, Java, PHP, and Python languages. Each SDK includes a proxy to all Bing Ads API web services and abstracts low level details of authentication with OAuth. You can use the high level BulkServiceManager and ReportingServiceManager interfaces to abstract and execute operations in the low level Bulk and Reporting services.
We have heard requests for additional SDKs e.g. Perl and Ruby, although there is no plan to add support in the near term.
How can I view code samples in different programming languages?
In addition to the Code Examples you'll find code snippets in many of the technical guides e.g., the Get Started guide. You can use the language selector at the top or right of those pages to view examples in CSharp, Java, Php, or Python. When you choose a language, the setting is retained as you navigate other pages. The language selector will only include languages that have samples for that specific page, and will default to C# if the language you had previously set is not available for the page that you navigated to.
Should I use the Bulk or Campaign Management API?
The Bulk service is recommended, especially if you need to add or update ads and keywords across multiple ad groups or campaigns in an account. Some features are not available in Bulk e.g. AddUetTags, GetBMCStoresByCustomerId, GetGeoLocationsFileUrl, and GetMediaMetaDataByAccountId. For these features of course you must use the Campaign Management service.
Which API performance reports are available and when will my data be available?
The Reporting service supports most of the same report types that you can find in the Microsoft Advertising web application. Be sure to check out the Report Attributes and Performance Statistics and Reporting Data Retention Time Periods guides for availability details.
When a user clicks an ad, it can take up to two hours for the system to process the click (3 hours for conversions) and make it available for reporting. When all data for the previous day have been processed and made available for reporting, this state is referred to as Books Closed. For more information about when the books are closed for reporting, see Time Zones in Reporting.
When will multi-factor authentication be required via Bing Ads API, Content API, and Hotel Price Ads API?
As of June 1, 2022, we're gradually requiring multi-factor authentication for customers signing in through third-party applications to use Bing Ads API, Content API, and Hotel API.
You must update your application to get user consent using the new
msads.manage scope. All application developers must take action to use the new scope.
For more information see the Multi-factor authentication requirement guide.
Do I need to make any changes to comply with the multi-factor authentication requirement?
You must update your application to use the new
msads.manage scope via the Microsoft identity platform endpoint. All application developers must take action to use the new scope.
You must prompt a user for consent via the new
msads.manage scope and the Microsoft identity platform endpoint.
Do I need to register a new application to use msads.manage?
If you have an older application ID (aka Client ID) that is formatted as a hexadecimal value e.g., 0000000012345A67, then you must register a new application. Valid Microsoft identity platform application IDs are formatted as a GUID with dashes e.g., ab01c23d-4e56-7f8a-90bc-1d23efabc45d. If you don't see an existing app in the Azure portal - App registrations, that's an indication that you should replace it with a new app.
Does a user need to grant consent when I upgrade to msads.manage?
Yes. You must prompt a user for consent via the new
msads.manage scope and the Microsoft identity platform endpoint.
What is the user experience when prompted for consent via the Microsoft identity platform endpoint?
When you prompt a user for consent (using the common tenant) with the Microsoft identity platform endpoint, the user sign in experience will vary depending on the underlying identity behind their credentials.
- A person who only has an MSA identity will be directed to the MSA sign in page.
- A person who only has an Azure AD identity will be directed to their organizational sign in page.
- A person whose credentials are valid in both the MSA and the Azure AD domains will encounter a disambiguation page that asks them to choose between their personal and their work or school identity. This disambiguation will always be present so long as this user has two identities tied to the same email address. The user can stop seeing this by changing the email address of their personal Microsoft account. For more information see https://cloudblogs.microsoft.com/enterprisemobility/2016/09/15/cleaning-up-the-azure-ad-and-microsoft-account-overlap/.
You should handle operation error codes 122 through 125 to help users of your application select the correct credentials i.e., work versus personal account.
When a user switches from using their personal account to their work or school account in Microsoft Advertising, what happens to their refresh token?
If the user no longer has an MSA personal account identity, then Bing Ads API will no longer accept their existing access token. Likewise, the refresh token can no longer be used to request a new access token, so you'll need to request user consent again for your application to manage their Microsoft Advertising accounts. You should discard the previous refresh token.
Does sandbox support work or school accounts?
No. Work or school accounts are only supported in production.
I want to run my application without user interaction. How can I authenticate without getting prompted for permission to use Microsoft Advertising credentials?
To programmatically manage a Microsoft Advertising account, you must provide consent at least once through the web application consent flow. For repeat or long term authentication, you should follow the authorization code grant flow for obtaining an access token and refresh token. Thereafter you can use the latest refresh token to request new access and refresh tokens without any further user interaction. You may need to request user consent again for example, if the user went through account recovery, changed their password, or otherwise removed permissions for your application to authenticate on their behalf.
When do the access and refresh tokens expire?
The access token typically expires after one hour, although you should always check the expiration time each time you request a new token.
Refresh tokens are, and always will be, completely opaque to your application. They are long-lived e.g., 90 days for public clients, but the app should not be written to expect that a refresh token will last for any period of time. Refresh tokens can be invalidated at any moment, and the only way for an app to know if a refresh token is valid is to attempt to redeem it by making a token request. Even if you continuously refresh the token on the same device with the most recent refresh token, you should expect to start again and request user consent if for example, you signed the user out, the Microsoft Advertising user changed their password, removed a device from their list of trusted devices, or removed permissions for your application to authenticate on their behalf. At any time without prior warning Microsoft may determine that user consent should again be granted. As a best practice you should always securely store the latest refresh token each time you request new access and refresh tokens.
Why do I need an access token and developer token?
The access token represents the user credentials who has access to one or more Microsoft Advertising accounts. The application ID (a.k.a. client_id) identifies your application for each Microsoft Advertising user who grants consent. The developer token gives your application permission to use the Bing Ads API.
Will Bing Ads API be rebranded along with the Microsoft Advertising platform?
Bing Ads is now Microsoft Advertising. Our new name reflects how we're growing our advertising solutions to help you reach more customers. There are no plans to rebrand any of the current API versions. The table below lists names that either have or haven't changed. For more information please see the brand announcement.
|Previous Name||Current Name|
|Ad Preview and Diagnostic Tool||Ad Preview and Diagnostic Tool|
|Bing Ads||Microsoft Advertising|
|Bing Ads Accredited Professionals||Bing Ads Accredited Professionals|
|Bing Ads API||Bing Ads API|
|Bing Ads App||Microsoft Advertising App|
|Bing Ads Content API||Bing Ads Content API|
|Bing Ads Editor||Microsoft Advertising Editor|
|Bing Ads Fans||Microsoft Advertising Fans|
|Bing Ads Intelligence||Microsoft Advertising Intelligence|
|Bing Ads Partner||Microsoft Advertising Partner|
|Bing Ads Scripts||Microsoft Advertising Scripts|
|Bing Ads SDK||Bing Ads SDK|
|Bing Hotel Center||Microsoft Hotel Center|
|Bing Merchant Center||Microsoft Merchant Center|
|Bing Network||Microsoft Advertising Network|
|Bing Network syndication||Microsoft Advertising Partner sites|
|Bing Partner Awards||Microsoft Advertising Partner Awards|
|Bing Partner Program||Microsoft Advertising Partner Program|
|Bing Shopping Campaigns||Microsoft Shopping Campaigns|
|Keyword Planner||Keyword Planner|
|Hotel Price Ads||Hotel Price Ads|
|Hotel API||Hotel API|