Bing Ads API Overview


Bing Ads is a pay-per-click (PPC) advertising platform used to display ads based on the keywords used in a user’s search query. For advertisers placing a large number of ads or developers building advertising tools, the Bing Ads API provides a programmatic interface to Bing Ads. Using the Bing Ads API is the most efficient way to manage many large campaigns or to integrate your marketing with other in-house systems. The Bing Ads API also supports multiple customer accounts making it easy for ad agencies to manage campaigns for many clients. Some organizations may choose a hybrid approach; using the web UI for most tasks but automating reporting or campaign optimization with the API.

You should consider using the Bing Ads API if your business model resembles the following:

When you advertise using Bing Ads, your search ads can appear on the search results page on websites throughout the world. These sites can include Bing, AOL, and Yahoo owned and operated sites as well as Bing, AOL, and Yahoo syndicated search partner sites. (Syndicated search partner sites are sites that use Bing and Yahoo search results.) For more information, see About ad distribution.

Your ads can appear on search results page when a customer does a search on Bing. Where you ad appears on search results pages is determined by the keywords you use to associate your ads. For example, Sarah owns a toy store and wants to create ads for kids’ electronics. She might include keywords like "walkie-talkies", "electronic pets", and "kids’ music players" so her ads could be more relevant to customers’ searches, and show above or next to the search results.


To see where Bing Ads is available and whether your ads will run, please see Where does Bing Ads show your ads? You can also set your ads to the languages your customers speak, which will influence where your ads will appear. For example, if Sarah wants her ads to be in German, her ads can appear not only in Germany but Austria and Switzerland as well. For more information, see Ad Languages.

You can extend the ad layout to be more visually appealing and feature rich using Ad Extensions.

Ad Extensions

With ad extensions, you can decorate ads with additional information that helps customers find relevant information about your products and services. For example, you can include deep links into your website to quickly direct your customers to relevant promotional or technical information that may help increase conversions. Bing Ads offers the following popular ad extension types. For more information please see Ad Extensions and Bing Ads Web UI Help - What are ad extensions?.

App Extensions

You can associate app ad extensions with your campaigns and ad groups, and text ads will include a link to install an application.

You can associate an app ad extension with one or more campaigns or ad groups, and a campaign or ad group can be associated with multiple app ad extensions.


Call Extensions

With Call Extensions, you can provide a phone number that is not associated with a particular location, but is appropriate for all locations where your ads display. In comparison, you typically use Location Extensions to provide an address and local phone number associated with a local location.

You may associate one call extension per campaign. If the campaign is also associated with a Location Extensions, the call extension phone number will override the location extension phone number.


Callout Extensions

With Callout Extensions, you can provide an extra snippet of text that highlights your business, products, or services to include in a text ad. This extension is not clickable and can appear in addition to your ad’s description. Providing additional details about your store can make your ad more relevant to potential customers.

You can associate a callout ad extension with one or more campaigns and ad groups. Each campaign or ad group can be associated with between 2 and 20 callout ad extensions. If you associate one or fewer callout extensions with your campaign or ad group, no callout text will serve with your ad. A text ad may include between 2 to 4 callouts per impression.

Callout ad extension

Image Extensions

You can associate image ad extensions with your campaigns and ad groups, and text ads may include an image or alternative text.

You may associate up to three image extensions per campaign or ad group.

Image Ad Extension

Location Extensions

When you enable Location Extensions, you can choose to show the address of your business location that is closest to the customer and also include a local phone number. Better yet, if the customer is viewing your ad on a smartphone, they can click that number to give you a call.

You may associate one or more location extensions per campaign. If the campaign is also associated with a Call Extensions, the phone number in the call extension will override the location extension phone number.


Review Extensions

Potential customers like to know about other customers’ experiences when searching for products or services. Share positive reviews from a reputable third-party source about your business, products, or services in your text ads with a Review Extension.

You can associate a review ad extension with one or more campaigns and ad groups. Each campaign or ad group can be associated with between 1 and 20 review ad extensions. A text ad will only include one review per impression.

Review ad extension

Sitelink Extensions

Sitelink Extensions are additional links in your ads that take customers to specific pages on your website. This allows you to promote certain products, services, or sections of your website and take potential customers to exactly the information they were searching for. This can increase both click-through-rate and conversions.

You may associate site links ad extensions with your campaigns or ad groups, and text ads will include up to 10 links to relevant web pages within your website. When displaying an ad, Bing Ads determines which links are most relevant to the ad being displayed and includes those with your ad. You can influence which links are included. Links that you specify at the beginning of your list receive higher priority than those toward then end of your list.

You may associate one site links ad extension per campaign or ad group.


Structured Snippet Extensions

Structured Snippet Extensions give potential customers more context on a specific aspect of your products and services. A Structured snippet is made up of a header and a list of 3-10 values which correspond to the header. For example, you might use the header “Brands:” and the values “Windows, Xbox, Skype” to let customers know about what brands are available at your store.

Structured Snippet Ad Extension

This extension is not clickable and, similar to other extensions, will appear beneath your ad’s description. Structured Snippets have no impact on the other extensions you’re already using. Structured Snippets should not duplicate what is already stated in the ad. Our full list of Structured Snippet policies can be found here.

You can associate a structured snippet ad extension with one or more campaigns and ad groups. Each campaign or ad group can be associated with between 1 and 20 structured snippet ad extensions. A text ad will only include one structured snippet (one headline with 3 - 10 values) per impression. Keep in mind that your ads won’t always show Structured Snippets and if they do show Structured Snippets, the format they appear may vary. Structured Snippets are free to add to your ad, available in all Bing Ads markets (excluding Hong Kong and Taiwan), and serve on desktop and tablet devices.

Bing Shopping Campaigns

A Bing Shopping campaign enables you to advertise the products from your Bing Merchant Center store product catalog. Product ads from a Bing Shopping campaign include details about the product, an image, and optional promotional text. After you create a product catalog, you can then submit the catalog feed using the Bing Ads Content API or FTP. For more information, please see Product Ads.

Your ads can appear specifically for customers on the go, who use their smartphones and tablets to search and browse the Internet. Or you can create ads that appear on both desktops and smartphones but prioritize where you want the ads to appear more often.


You can show your ads to customers in specific locations, like cities or countries. For example, Sarah wants only local customers to see her ads. She can set your ads to appear to customers within a 20-mile radius around her shop by using radius targeting.

You can also setup your ads to display to users of a certain age group or gender, or to display at a certain day and time of the week. For more information about showing ads to your target audience, see Show Ads to Your Target Audience.

You will want to optimize your campaign budget and keyword bids for a competitive advantage. The Bing Ads API Ad Insight service uses historical performance, web page data, and demographic data to provide data and bid suggestions that you may find helpful as you optimize your campaigns over time. For more information, see Budget and Bid Opportunities.

Once your campaigns are up and running, you’ll want to monitor their performance using the Bing Ads Reporting service. Bing Ads can generate reports to track ad delivery, budget, and targeting. Each report type aggregates data at a different level and provides different Report Attributes and Performance Statistics. For example, You would use the account and campaign performance reports to monitor click and spend data to ensure that you are optimizing your budget, and you would use the ad and keyword performance reports to identify ads and keywords that are performing well in terms of click-through rate and conversions. For more information, see Reports.

The Bing Ads Developer Center aggregates valuable resources for the Bing Ads developer community, including links to getting started, account management, service health dashboard, code samples, support, and feature announcements.

The blog contains technical information about upcoming features not currently in the MSDN documentation; issues that API customers are facing and clarification and/or a solution to those issues; updates about Sandbox availability; and information about when a version of the service is going to sunset.

The forum provides a way for the developer community to ask and answer questions about developing solutions with Bing Ads APIs, to showcase innovations, and to generate and maintain content through community participation. Microsoft monitors the forums and replies to questions that the community has not yet answered.

If you are not finding the information you need to solve your problem in the developer forum, please contact Bing Ads Support. To resolve the issue efficiently, please provide support with the details requested in Engaging Support.

Q. What are the requirements to use the Bing Ads API?

To get started, you need to sign up for a Bing Ads account, and then get your developer token at the Developer Portal.

Q. Which programming languages and SDKs are supported?

You can develop Bing Ads applications with any programming language that supports web services. The Bing Ads Software Development Kits (SDK) enhance the experience of developing Bing Ads applications with .NET, Java, 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.

Although not in parity with the .NET, Java, and Python SDK features, the Bing Ads PHP Class Library is available to jump start your PHP application development.

We have received requests for additional SDKs e.g. Python and Ruby, although there is no plan to add support in the near term.

Q. Which API version should I use?

You should always use the latest version as soon as we announce support via the blog or release notes. As of February 2017 Version 10 was the highest supported version for Ad Insight, Bulk, and Campaign Management API, and Version 9 was the highest supported version for Customer Billing, Customer Management, and Reporting API. We have heard feedback that it would reduce friction if all services are supported on the latest version. Starting with Bing Ads API Version 11 (Early Q2 2017) and going forward, we will support all services in the latest version.

Q. 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 GetMediaByIds. For these features of course you must use the Campaign Management service.

Q. 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 Bing Ads 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 Determining When the Books Close.

Q. I want to run my application without user interaction. How can I authenticate without getting prompted for permission to use Bing Ads credentials?

To programatically manage a Bing Ads 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 Microsoft Account password was changed or the Microsoft Account owner removed permissions for your application to authenticate on their behalf.

Q. 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. The refresh token does not have a published duration or expiration time, although you can expect it to last up to 1 year. As a best practice you should always securely store the latest refresh token each time you request new access and refresh tokens.

Entity Hierarchy and LimitsRefer to this guide for a high level view of system limits for Bing Ads entities.
Getting Started With the Bing Ads APITo use the API, you’ll first need a Bing Ads developer token and valid user credentials. Learn how to get developer credentials and how to write your first application for example, in C#, Java, PHP, or Python.
SandboxYou may test your application in the Bing Ads sandbox environment before deploying it to the production environment.
Client LibrariesYou can develop Bing Ads applications with any programming language that supports web services. The Bing Ads Software Development Kits (SDK) enhance the experience of developing Bing Ads applications with .NET, Java, and Python languages.
Code ExamplesJump start your development by viewing or using the examples provided in C#, Java, PHP, and Python.
Technical GuidesLearn about how to integrate core advertising solutions using Bing Ads services.
API ReferenceBrowse programming elements such as service operations, data objects, and value sets for each Bing Ads web service.
Release NotesStay informed about the changes to the Bing Ads services for each release.