S2S Integration — Upload revenue to Bing Ads without an SDK

5 min readJan 27, 2021

Find out how to interact with Bing Ads API without an SDK

If you are using Bing to advertise your product or generate leads, you might want to use Bing Ads platform to track conversion and revenue. You can add revenue manually or through an excel bulk upload but as your company grows, you are more likely to look into automation by using an API.

The Bing Ads API uses Simple Object Access Protocol (or SOAP) requests and responses, an XML message which looks like this:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <NumberToWords xmlns="http://www.dataaccess.com/webservicesserver/">
      <ubiNum>500</ubiNum>
    </NumberToWords>
  </soap:Body>
</soap:Envelope>

Not great.

To facilitate the implementation of Bing Ads APIs in your application, Microsoft provides a Software Development Kit (or SDK) for several languages (C#, Java, PHP, and Python), which means you don’t have to write any SOAP request. Unfortunately, there is no SDK available for JavaScript, so we will have to make peace with SOAP requests.

I’m going to use Postman, a great tool to test APIs without writing a single line of code, to show you how you can use Bing Ads API without an SDK.

I. Getting Started

What you need to get started:

Microsoft Ads account (sign in here: https://ads.microsoft.com/)
Access to the Azure portal
A valid Microsoft click id (a unique 32 characters long GUID generated when an ad is clicked)
Basic understanding of Postman

II. Create an Offline Conversion Goal

To be able to upload revenue, you first need to create a conversion goal with a unique name. Go to Microsoft Ads platform, open the campaign for which you want to upload revenue, and click on Tools > Conversion tracking > Conversion Goal.

Click on Create Conversion Goal, enter a unique name, and select Offline Conversions. Click on Next and fill in your preferences. For more details on the possible options, check out Microsoft documentation here.

Once created, note that you will have to wait 2 hours before uploading revenue against this conversion goal.

III. Authenticate and get and access token

Every time you send a request to the API, you need to use a short-lived access token (typically expires in 60 minutes).

There are 2 ways to get an access token:

Live Connect
Microsoft identity platform

Microsoft recommends using the Microsoft identity platform so I will use this method to authenticate. If you get stuck in one of the below steps, don’t hesitate to check the official documentation here.

1. Register your application

First, register your application in the Azure Portal by clicking on New Registration. Once you registered your application, it will generate an application id also called client id (eg: 6731de76–14a6–49ae-97bc-6eba6914391e) which you will need for the next step.

Select the Add a redirect URI link and make sure to select at least the redirect URI: https://login.microsoftonline.com/common/oauth2/nativeclient.

2. Request user consent

You need to provide consent for your application by generating an authorization code. Copy the below URL and fill in your client id.

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=https%3A%2F%2Flogin.microsoftonline.com%2Fcommon%2Foauth2%2Fnativeclient
&scope=openid%20offline_access%20https%3A%2F%2Fads.microsoft.com%2Fads.manage

Paste the URL in your browser (note that this won’t work through Postman). It will prompt you to the Microsoft login portal where you’ll need to authenticate and consent permission for your app to manage your Microsoft accounts. Once done, you should be redirected to a blank page with an authorization code in the URL:

https://login.microsoftonline.com/common/oauth2/nativeclient?code=YOUR_AUTHORIZATION_CODE_HERE

Save that authorization code for the next step. Note that it will expire after a few minutes.

3. Get a Refresh Token

Create a Postman POST request to https://login.microsoftonline.com/common/oauth2/v2.0/token/

Selected body x-www-form-urlencoded and fill with the following values:

client_id: your client id
code: the authorization code obtained earlier
grant_type: code
redirect_uri: https://login.microsoftonline.com/common/oauth2/nativeclient
scope: https://ads.microsoft.com/ads.manage offline_access
tenant: common

Hit Send. You should get back an access token and a refresh token.

4. Refresh the access token

The access token generated above will only last for 60 minutes.

To refresh your access token, create a Postman POST request to https://login.microsoftonline.com/common/oauth2/v2.0/token/

Select body x-www-form-urlencoded and fill with the following values:

client_id: your client id
refresh_token: your refresh token
grant_type: refresh_token
redirect_uri: https://login.microsoftonline.com/common/oauth2/nativeclient
scope: https://ads.microsoft.com/ads.manage offline_access
tenant: common

Hit Send. You should get back a new access token. As the refresh token is long-lived (90 days), you should be able to reuse this request every time you need a new access token. Note the response also returns a new refresh token.

IV. ApplyOfflineConversions

Now that you have your access token, you can finally interact with Bing Ads API! We are close to making our first revenue upload!

Create a new Postman POST request to https://campaign.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/V13/CampaignManagementService.svc?singleWsdl

Set the headers to:

Content-Type: text/xml;charset=utf-8
SOAPAction: ApplyOfflineConversions

In body, select the type “raw” and “XML”. Copy the request SOAP template provided in Microsoft’s documentation, paste it in the body of your Postman request and fill in the missing values:

Envelope headers:

AuthenticationToken: access token from Part III
CustomerAccountId and CustomerId: you can find it on Microsoft Ads web application’s url when selecting an account: https://ui.ads.microsoft.com/campaign/vnext/overview?cid=CustomerIdHere&aid=CustomerAccountIdHere
You can also call GetUser and GetAccountInfo to obtain it through an API request.
Your developer token: more info here

Envelope body:

Currency Code (eg: GBP)
Conversion Name: the name you gave to the conversion goal in Part II
Conversion Time: a date and time value (eg: 2021–01–27T15:13:13+00:00). Make sure the date and time value is later than the date and time of the recorded click and is within the conversion window (max 90 days from click).
ConversionValue: revenue generated
MicrosoftClickId: make sure the click id has been generated from the account id set in the header CustomerAccountId.

It should look like the below (with your account ids and tokens filled in of course):

Hit Send. You should get back a response with an empty PartialErrors tag.
The revenue will show up in Tools>Conversion Tracking > Conversion Goals within 5 hours.

Wrapping Up

I hope this article gave you an idea of how to use Bing Ads APIs without an SDK. Do not hesitate to leave a comment if you have a question and I’ll try my best to help you. Otherwise, you can ask a question on Microsoft Developer Forum.