Bing Ads custom push

This article describes a broad overview how you could create a custom push to bing ads.

This guide assumes that you already set up an microsoft OAuth account with the scope "https://ads.microsoft.com/msads.manage". If this is not the case please check out this article Microsoft OAuth.

The push will send the information to the bing ads API via the "ApplyOfflineVersions" method. https://docs.microsoft.com/en-us/advertising/campaign-management-service/applyofflineconversions?view=bingads-13

This method creates an offline conversion using the given microsoft click id.

In addition this guide assumes you already set up an offline conversion goal in your bing ads account with auto tagging enabled. To learn how to set up your account please check out the bing ads documentation.

What do we need?

Variable Description
CustomerAccountId The id of your ads account that will receive the information. Where to find the Account and Customer Id
CustomerId The id of your ads account that will write those information. Where to find the Account and Customer Id
DeveloperToken To write information to the ads api you need to create a developer token. How to create a developer token

Where to find the CustomerAccountId & CustomerId?

These values are within the url of your campaign in bing ads. The fields are named "aid" and "cid".

The value of "aid" is your CustomerAccountId and the value of "cid" is the CustomerId.

How to setup an developer token?

The setup instructions for a developer token can be found using the following link to microsoft's documentation. How to create a developer token

Setup push in matelso control panel

To setup the push in the matelso control panel we navigate to "Configuration" -> "Integrations 2.0" and click on "Custom".

In the form we enter the name of this push and an event trigger. For this example I use the name "Bing Ads" and the trigger "POST-Call". Which trigger do I need (Pre or Post)?

After configuring these values we add an filter that prevents the push from being triggered if there is no microsoft click id ("MSCLKID").

After that we jump to the end of the page and configure where to send the push. For Bing Ads we setup the following url:

https://campaign.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/CampaignManagementService.svc

After splitting the url to the correct form fields it looks like the following screenshot:

After we set up the destination for our push we configure what to send. In the "What?" area of the form we set up 2 HTTP-Header.

After that we choose "POST" as the HTTP-Method.

Now we fill in the "POST Body". Bing Ads is a so called SOAP Api which means we have to fill in a quite big chunk of XML with some placeholders we need to replace.

<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/v13">
    <Action mustUnderstand="1">ApplyOfflineConversions</Action>
    <AuthenticationToken i:nil="false"> {{configData.accounts.basicOAuth2Credentials.msoauth.accessToken}} </AuthenticationToken>
    <CustomerAccountId i:nil="false">$CustomerAccountId$</CustomerAccountId>
    <CustomerId i:nil="false">$CustomerId$</CustomerId>
    <DeveloperToken i:nil="false">$DeveloperToken$</DeveloperToken>
  </s:Header>
  <s:Body>
    <ApplyOfflineConversionsRequest xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
      <OfflineConversions i:nil="false">
        <OfflineConversion>
          <ConversionCurrencyCode i:nil="false">EUR</ConversionCurrencyCode>
          <ConversionName i:nil="false">$ConversionGoalName$</ConversionName>
          <ConversionTime> {{callData.totalCallBeginTime.datetimeFormatter(yyyy-MM-ddTHH:mm:ss)}} </ConversionTime>
          <ConversionValue i:nil="false">1</ConversionValue>
          <MicrosoftClickId i:nil="false"> {{webData.location.query.msclkid.attribution(LASTNOTEMPTY)}} </MicrosoftClickId>
        </OfflineConversion>
      </OfflineConversions>
    </ApplyOfflineConversionsRequest>
  </s:Body>
</s:Envelope>

We look for the following placeholders and replace them accordingly:

Placeholder Description
$CustomerAccountId$ The CustomerAccountId we looked up earlier.
$CustomerId$ The CustomerId we looked up earlier.
$DeveloperToken$

Our freshly created developer token.

$ConversionGoalName$

Name of our offline conversion goal we set up in Bing Ads.

Now we click the "save" button and connect our push to the pools or the partner id.