> For the complete documentation index, see [llms.txt](https://documentation.freshpaint.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/bing-insights/bing-insights-quick-start-guide.md). # Bing Insights Quick Start Guide ### Prerequisites Before you begin, ensure you have the following: 1. Microsoft Advertising account with active ad campaigns 2. Add the service principal of Microsoft Advertising API Service to your organization. 1. This step is done via Microsoft Entra and therefore requires a Global Administrator or Cloud App Administrator to create the service principal. This doesn't immediately give any third parties access to your Advertising API. **This simply allows users to obtain OAuth tokens for the Microsoft Advertising service.**

If the Microsoft Advertising API service principal is not added, OAuth will fail.

3. Active ad campaigns - The integration pulls data from your running or completed campaigns {% hint style="info" %} Note for agency-managed accounts: If your Microsoft Ads account is managed by an agency, you may need to coordinate with them to grant appropriate access before authenticating. {% endhint %} ### Permissions There are two Microsoft systems that each play a role in authentication/authorization for this integration: Microsoft Entra and Microsoft Advertising. Microsoft Entra is the authentication layer. It's what governs if users can create access tokens or not for the Microsoft Advertising service. If you run into issues related to admin consent, please contact your tenant administrator. They must allow the Microsoft Advertising API Service in Entra for the OAuth flow to be successful. The authorization layer is governed by the Microsoft Advertising service. Authorization is determined by the role of the user who connects the integration via OAuth. Our OAuth flow requests two scopes: `msads.manage` and `offline_access`. The `offline_access` scope allows Freshpaint to refresh the access token. The `msads.manage` scope is the standard scope needed for access to the Microsoft Advertising API. Microsoft doesn't have finer-grained scopes that are read-only permissions. This scope does provide access to the full suite of CRUD operations via the Microsoft Advertising API. Our system does not call any write-endpoints. We only call read-endpoints. Remember from the previous paragraph that authorization is limited by the role of the user who connects the integration via OAuth. The msads.manage represents the maximum set of permissions, not the actual set of permissions. If the OAuth flow is done by a Viewer user, the access tokens will be limited to that user's permissions, which means Freshpaint will only have access to read data, not write data via the Microsoft Advertising API. ### Getting Started 1. Get Your Ad Account IDs * Navigate to [https://ads.microsoft.com](https://ads.microsoft.com/) and sign in * Click on "Settings" * Your Account ID can be found under "Account Settings" \* ```
``` * Your Manager Account ID can be found under "Manager account settings" \* ```
``` 2. Get Your Developer Tokens * In Microsoft Ads, go to Settings > Developer Settings * The user capturing the Developer Token must be a Standard User or higher. Viewer users cannot generate a Developer Token. The Developer Token doesn't have to be tied to the user that will connect with OAuth. * Copy your Developer Token \* ```
``` 3. Create the Bing Insights Destination in Freshpaint * In Freshpaint, navigate to your [Destinations page](https://app.freshpaint.io/destinations/catalog?category=overview) and search for Bing Insights * Enter your Developer Token, Account ID, and Manager Account ID \* ```
``` 4. Click "Connect with Microsoft" 1. **Important:** If you want to restrict Freshpaint's access to the Microsoft Advertising API, you should "Connect with Microsoft" using a user with a Viewer role.
5. Enable Destination * Click on the "Enable" button at the top of the configuration settings ### Configuring Attribution Parameters The Insights Attribution page shows performance for each individual Microsoft Advertising campaign. This breakdown relies on two inputs: campaign spend, which Freshpaint pulls automatically from the Microsoft Advertising API, and a mapping between each ad click and the campaign it came from. Microsoft Advertising does not expose that click-to-campaign mapping through its API, so a tracking template adds the campaign ID to each ad click URL instead. Once the tracking template is live, Freshpaint reads the campaign ID from the `mscid` parameter on each incoming click and attributes the click to that campaign automatically. #### 1. Open the account-level tracking template This setup uses a Microsoft Advertising tracking template, which can be set at the account level. In Microsoft Advertising, go to **Campaigns → Settings → Account level options → Tracking template**. Microsoft recommends setting the tracking template at the account level so it applies to every campaign in the account, including campaigns added later. For Microsoft's full list of tracking parameters, see [Microsoft Advertising: URL tracking with upgraded URLs](https://learn.microsoft.com/en-us/advertising/guides/url-tracking-upgraded-urls). #### 2. Set the tracking template value For an account with no existing tracking template, set the value to: ``` {lpurl}?mscid={CampaignID} ``` For an account that already has a tracking template, append the parameter to the end of the current value instead: ``` &mscid={CampaignID} ``` `{lpurl}` is a required Microsoft placeholder for the landing page URL. `{CampaignID}` is a Microsoft Advertising parameter that Microsoft replaces with the campaign's ID each time an ad is clicked. `mscid` is the parameter key Freshpaint reads, so enter it exactly as shown. {% hint style="warning" %} **Configure every active campaign.** Freshpaint pulls spend for all campaigns from the Microsoft Advertising API, but a click only maps to a campaign when that campaign's URLs carry `mscid={CampaignID}`. When some campaigns are missing it, their cost per acquisition (CPA) appears inflated, because Freshpaint counts the spend for those campaigns but cannot match their conversions. Setting the tracking template at the account level is the most reliable way to cover every campaign. {% endhint %} {% hint style="info" %} **Data starts at setup - not retroactively.** Campaign breakdown data starts populating only after this setup is complete. Clicks that happened before the parameter was in place are not attributed to a campaign. {% endhint %} #### 3. Verify campaign breakdown in Insights After the tracking template is live and new clicks have arrived, open the **Attribution page** in Insights and expand the Microsoft Advertising (Bing) source. Clicks that Freshpaint cannot match to a campaign appear under an `UNKNOWN` row. A large or growing `UNKNOWN` row could mean one or more campaigns are still missing the `mscid={CampaignID}` parameter. {% hint style="success" %} **Success:** Individual campaign names appear in the campaign breakdown, and the `UNKNOWN` row stays small relative to total volume. {% endhint %} ### Best Practices & Reminders **Set the tracking template at the account level** Adding `fp_insights_cid={CampaignID}` once at the account level covers every current campaign and any campaign created later. Reserve per-campaign overrides for campaigns that genuinely need different URL options. **Monitor the `UNKNOWN` row** Check the `UNKNOWN` campaign row in the campaign breakdown periodically. Growth in that row usually means a new campaign shipped without the parameter. Add the parameter to that campaign to restore accurate attribution going forward. **No Retroactive Data** Campaign breakdown reflects clicks captured after setup only. Note the date the parameter went live so campaign-level numbers are read in the correct time context. **Coordinate with the agency for managed accounts** For agency-managed Microsoft Advertising accounts, have the agency add the parameter to the account URL options, since that team controls campaign configuration. ### What's Next? * **Configure other ad platforms** — Freshpaint uses the same campaign-ID pattern across ad platforms. Set up the [Google Ads campaign ID parameter](https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/google-ads-conversion-api/google-ads-conversion-api-quick-start-guide#add-the-campaign-id-to-your-final-url-suffix) and the [Meta Insights URL parameters](https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/meta-insights/meta-insights-quick-start-guide#required-url-parameters) to enable campaign breakdown for those platforms. * **Review campaign performance in Insights** — Open Bing Insights, select **Group By Campaigns**, and compare spend and conversions across campaigns to guide budget decisions. * **Monitor attribution health** — Keep the `UNKNOWN` campaign row small by confirming every new campaign inherits the `fp_insights_cid={CampaignID}` parameter.