Get Started With the Bing Ads API

Any Bing Ads user with a developer token can begin using the Bing Ads API. For advertisers placing a large number of ads or developers building advertising tools, the Bing Ads API provides a programmatic interface to Bing Ads. You can write your Bing Ads application in any language that supports web services. To get started with a specific SDK, see Get Started in C# | Java | PHP | Python.

Get a Developer Token

To use Bing Ads APIs, you must have a developer token and valid user credentials.

The sandbox and production environments use separate credentials. You can sign up for a Sandbox account here. Everyone can use the universal sandbox developer token i.e., BBD37VB98.

Where to Use the API Credentials

When you call a service operation such as GetCampaignsByAccountId, you must specify request header elements such as DeveloperToken, CustomerId, and CustomerAccountId.

<s:Envelope xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header xmlns="https://bingads.microsoft.com/CampaignManagement/v11">
    <Action mustUnderstand="1">GetCampaignsByAccountId</Action>
    <ApplicationToken i:nil="false">ValueHere</ApplicationToken>
    <AuthenticationToken i:nil="false">ValueHere</AuthenticationToken>
    <CustomerAccountId i:nil="false">ValueHere</CustomerAccountId>
    <CustomerId i:nil="false">ValueHere</CustomerId>
    <DeveloperToken i:nil="false">ValueHere</DeveloperToken>
    <Password i:nil="false">ValueHere</Password>
    <UserName i:nil="false">ValueHere</UserName>
  </s:Header>
  <s:Body>
    <GetCampaignsByAccountIdRequest xmlns="https://bingads.microsoft.com/CampaignManagement/v11">
      <AccountId>ValueHere</AccountId>
      <CampaignType>ValueHere</CampaignType>
    </GetCampaignsByAccountIdRequest>
  </s:Body>
</s:Envelope>

If you are using one of the Bing Ads SDKs, the request header elements are set using AuthorizationData. For more details about the SDK authentication library see Authentication With the SDKs.

var authorizationData = new AuthorizationData
{
    Authentication = <AuthenticationGoesHere>, 
    CustomerId = <CustomerIdGoesHere>,
    AccountId = <AccountIdGoesHere>,
    DeveloperToken = "<DeveloperTokenGoesHere>"
};
static AuthorizationData authorizationData = new AuthorizationData();
authorizationData.setAuthentication(<AuthenticationGoesHere>);
authorizationData.setCustomerId("<CustomerIdGoesHere>");
authorizationData.setAccountId("<AccountIdGoesHere>");
authorizationData.setDeveloperToken("<DeveloperTokenGoesHere>");
$authorizationData = (new AuthorizationData())
    ->withAuthentication($AuthenticationGoesHere)
    ->withCustomerId($CustomerIdGoesHere)
    ->withAccountId($AccountIdGoesHere)
    ->withDeveloperToken($DeveloperTokenGoesHere);
authorization_data = AuthorizationData(
    authentication = <AuthenticationGoesHere>,
    customer_id = <CustomerIdGoesHere>,
    account_id = <AccountIdGoesHere>,
    developer_token = '<DeveloperTokenGoesHere>'
)

Get Your Account and Customer Ids

To get a user's customer ID and account ID, you can sign in to the Bing Ads web application and click on the Campaigns tab. The URL will contain a cid key/value pair in the query string that identifies your customer ID, and an aid key/value pair that identifies your account ID. For example, https://ui.bingads.microsoft.com/campaign/Campaigns.m?cid=FindCustomerIdHere&aid=FindAccountIdHere#/customer/FindCustomerIdHere/account/FindAccountIdHere/campaign.

With the Customer Management API you can get the customer and account identifiers for each authenticated user.

Call GetUser with your Bing Ads credentials and DeveloperToken. Within the Body set the UserId nil. The response will include a User object that contains the UserId.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Header>
    <h:ApplicationToken i:nil="true" xmlns:h="https://bingads.microsoft.com/Customer/v11" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
    <h:AuthenticationToken xmlns:h="https://bingads.microsoft.com/Customer/v11">OAuthAccessTokenGoesHere</h:AuthenticationToken>
    <h:DeveloperToken xmlns:h="https://bingads.microsoft.com/Customer/v11">DeveloperTokenGoesHere</h:DeveloperToken>
    <h:Password i:nil="true" xmlns:h="https://bingads.microsoft.com/Customer/v11" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
    <h:UserName i:nil="true" xmlns:h="https://bingads.microsoft.com/Customer/v11" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
    </s:Header>
    <s:Body>
    <GetUserRequest xmlns="https://bingads.microsoft.com/Customer/v11">
        <UserId i:nil="true" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
    </GetUserRequest>
    </s:Body>
</s:Envelope>

Then call SearchAccounts with the UserId returned via the previous step. The returned advertiser account (or accounts) will include account and customer identifiers.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Header>
    <h:ApplicationToken i:nil="true" xmlns:h="https://bingads.microsoft.com/Customer/v11" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
    <h:AuthenticationToken xmlns:h="https://bingads.microsoft.com/Customer/v11">OAuthAccessTokenGoesHere</h:AuthenticationToken>
    <h:DeveloperToken xmlns:h="https://bingads.microsoft.com/Customer/v11">DeveloperTokenGoesHere</h:DeveloperToken>
    <h:Password i:nil="true" xmlns:h="https://bingads.microsoft.com/Customer/v11" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
    <h:UserName i:nil="true" xmlns:h="https://bingads.microsoft.com/Customer/v11" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
    </s:Header>
    <s:Body>
    <SearchAccountsRequest xmlns="https://bingads.microsoft.com/Customer/v11">
        <Predicates xmlns:a="https://bingads.microsoft.com/Customer/v11/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <a:Predicate>
            <a:Field>UserId</a:Field>
            <a:Operator>Equals</a:Operator>
            <a:Value>UserIdGoesHere</a:Value>
        </a:Predicate>
        </Predicates>
        <Ordering i:nil="true" xmlns:a="https://bingads.microsoft.com/Customer/v11/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
        <PageInfo xmlns:a="https://bingads.microsoft.com/Customer/v11/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <a:Index>0</a:Index>
        <a:Size>10</a:Size>
        </PageInfo>
    </SearchAccountsRequest>
    </s:Body>
</s:Envelope>

Tip

See Search User Accounts Code Example for a code example that returns accounts for the current authenticated user.

Request Header Elements

Bing Ads services use Simple Object Access Protocol (SOAP) to exchange the request and response messages with the service operation. For more information, see Bing Ads Services Protocol.

Each SOAP request must include the following SOAP headers, which contain the user's credentials.

Element Description Data Type
ApplicationToken This header element is not used and should be ignored. string
AuthenticationToken The OAuth access token that represents a Microsoft Account user who has permissions to Bing Ads accounts. string
CustomerAccountId The identifier of the account that owns the entities in the request. This header element must have the same value as the AccountId body element when both are required. string
CustomerId The identifier of the customer that contains and owns the account. If you manage an account of another customer, you should use that customer ID instead of your own customer ID. string
DeveloperToken The developer token used to access the Bing Ads API. string
Password The Bing Ads managed user's sign-in password. string
UserName The Bing Ads managed user's sign-in name. You must not set this element to a Microsoft account or email address. string

Important

The UserName and Password header elements are deprecated. In future versions of the API, Bing Ads will transition exclusively to Microsoft Account (email address) authentication. For more information, see Authentication with OAuth. UserName and Password are still required for Bing Ads managed credentials, but they are not applicable for Microsoft account authentication. To authenticate a Microsoft account, use the AuthenticationToken] header instead of UserName and Password.

Warning

Do not mistake the account number for the account identifier. The account number is the system generated account number that is used to identify the account in the Bing Ads web application. The account number has the form xxxxxxxx, where xxxxxxxx is a series of any eight alphanumeric characters. The API service requests only use the account identifier, and never use the account number.

Note

With the exception of the Customer Billing and Customer Management services, the CustomerAccountId and CustomerId are required for most service operations. As a best practice you should always specify them in the request.

Need Help?

For troubleshooting tips, see Handling Service Errors and Exceptions.

To get help with issues that you cannot resolve, consider posting in the API Developer Forum where an active Bing Ads product team or community member will try and help. If you do not find timely information via the developer forum, or if the investigation involves sensitive account or personal details, please contact Bing Ads Support.

See Also

Bing Ads Technical Guides
Bing Ads API Reference