Bing Ads Services Protocol

Bing Ads Services Protocol

You can write your Bing Ads application in any language that supports web services. A web services description language (WSDL) document is defined for each web service. The WSDL defines the operations that a web service offers and the format of the request and response messages that the client sends to and receives from the operations. The request and response messages define the names and types of the data that the client exchanges with the operation. For more information about WSDLs, see the W3C WSDL specification.

Bing Ads services support Simple Object Access Protocol (SOAP). Some languages, such as C# and Java, provide tools that generate proxy classes from the WSDL. If your language of choice does not provide a tool to generate proxy classes, you will need to generate your own proxy classes or SOAP envelopes. To generate the proxy classes, you need the web address of the WSDL document of the service that you want to use. The Bing Ads sandbox and production environments each have a unique address. The addresses also include the version number of the WSDL that is specific to a major Bing Ads API release. For production and sandbox service WSDLs of the latest Bing Ads API version, see Bing Ads Web Service Addresses.

When you create a SOAP request message, the order of the elements within the SOAP body is critical. The elements must be in the same order as defined in the web services description language (WSDL). If the required elements are out of order, the call will fail. If the optional elements are out of order, the call may fail or the elements will be ignored. The WSDL syntax, which shows the correct order of the elements, is included with each request message, response message, and data object documented in the reference content. In addition, each request and response message shows an example SOAP envelope.

System_CLiX_note Note

XML is case-sensitive. You must use the correct case for the value names. Strongly-typed programming languages such as C# ensure that you have the correct case before you can compile. Other languages might not give you a compile error if the correct case is not used; however, the code fails at run time.

Bing Ads API Version 9 supports partial completions for add, update, and delete operations; if one of the objects in the list of objects that you are adding, updating or deleting fails, the operation may succeed for others in the collection. When you call a Get operation that takes a list of identifiers for example, the GetKeywordsByIds operation, and one of the identifiers in the list is not valid, the operation will succeed and the response element that corresponds to the invalid request identifier will be null.

Partial update is supported for most, but not all campaign management data objects. For example when updating the DestinationUrl of a TextAd you need only specify the Id and DesinationUrl elements. All remaining optional elements may be left empty and their existing settings are retained in the Bing Ads system. You should set all fields that you are not updating to null, unless otherwise indicated by the documentation for the corresponding data object.

System_CLiX_note Note

Note that the customer management service performs a full update of entities, so you must provide values for all fields that you do not want to be null.

Partial update is not supported for targets or ad extensions. Any optional elements which are not sent with the update request will in effect be deleted from the respective target or extension.

You should maintain a local store of your account and campaign entities. Specifically, you should locally store the identifiers of your accounts, customers, campaigns, ad groups, and keywords. Most calls require the identifier of the entity. If you store the identifier, you eliminate the call that is required to get the identifier.

For example, many of the campaign management calls require an account identifier. To get the account identifier, you can use the customer management service. However, instead of calling the service repeatedly, store the account identifier locally, so that you can use it in subsequent calls.

The following are the overhead costs, in processing time, that are associated with each web service call.

  • Establishing an HTTPS connection to the web service.

  • Authenticating the user name and password.

  • Validating the developer token.

These costs occur whether you process a single item or a set of items. To minimize overhead, in general, you should try to process as many items in one call as possible. For example, instead of calling UpdateCampaigns for each campaign that you want to update, call it only once for multiple campaigns that you want to update. To manage large scale data you should use the Bulk service. The Bulk service allows you to download data as a TSV or CSV file, modify it as needed, and then upload your changes. For more information about using the Bulk service, see Downloading and Uploading Campaigns.

Because of the costs associated with establishing a connection to a web service, you should maintain the connection for as long as it is needed. For example, if you need to request multiple reports, use the same reporting service client object for all reporting service operation calls. Explicitly close the connection when you no longer need the service.

Throttling extremely high-volume usage maintains fair usage for all Bing Ads clients.

Ad Intelligence and Campaign Management

For Ad Intelligence and Campaign services, throttling limits the number of calls to the API that any one user can make in a minute’s time. 

At the customer level, the number of calls a customer can make to the customer data is restricted using a sliding protocol with a 60 second window. 

Should you hit the service call limit, you will see the following error:

  • Numeric Error Code: 117

  • Symbolic Error Code: CallRateExceeded

  • Message: You have exceeded the number of calls that you are allowed to make in a minute. Please reduce the number of calls that you make per minute. 

When you observe this error, you can resubmit the request under the limit after waiting 60 seconds.


The Bulk service limits the number of requests that you can make to DownloadCampaignsByAccountIds, DownloadCampaignsByCampaignIds, and GetBulkUploadUrl. The details of the service limits are internal and subject to change.

Should you hit the service call limit, you will see the following error:

  • Numeric Error Code: 4204

  • Symbolic Error Code: BulkServiceNoMoreCallsPermittedForTheTimePeriod

  • Message: Too many bulk calls have been submitted. Please wait a few minutes and try again later.

If you observe this error, you can resubmit your request after waiting up to 15 minutes.

Community Additions

© 2015 Microsoft