Microsoft Ads Conversions API Quick Start Guide

Send advertising conversion events directly to Microsoft Ads

The Microsoft Ads Conversions API destination is currently in Early Access. Please contact [email protected] for more information about this integration.

Destination Info

• Supports Track calls

• Supports HIPAA mode

• Supports forwarding from the Google Tag Manager Integration

• Refer to this destination as Microsoft Ads Conversions API in the Integrations object

  • If you've configured multiple Tag IDs, you can choose a specific one by suffixing the Tag ID, such as: Microsoft Ads Conversions API::1234123456. You can retrieve this value from the Microsoft Ads Conversions API configuration page for the Tag ID of interest.

• Connection Modes:

	Client-side	Server-side
Web
Mobile
Server

Getting Started

This guide enables you to fully enable the Microsoft Ads Conversions API destination for your site. This guide assumes you have the Freshpaint snippet installed on your site — if you do not, please follow this guide.

Create a Universal Event Tracking (UET) Tag

You can skip this step if you'd like to re-use an existing tag.

1. Click Conversions → UET tag

1. Click + Create to create a new tag.

1. Give your tag a name, for example the name of your website, then click Save and next.

1. Select Use Conversions API and copy the Token on the following page.

The Use Conversions API option is not available by default. To enable this feature, contact your Microsoft Account Manager.

1. Copy the token on the next page.

1. Once your tag is created, copy the Tag ID from the Tag ID column on the UET Tag page.

Enable the Freshpaint Microsoft Conversions API destination

1. Navigate to the Freshpaint Destinations page.

2. Search for the Microsoft Conversions API destination.

3. Select Configure to paste your Tag ID and Token from the above steps.

4. Customers that use HIPAA mode should then configure the required, recommended, and recommended view-through properties. You can find all properties that the Freshpaint Microsoft Conversions API integration supports here.

5. Enable Microsoft Conversions API.

Once you've followed the steps above you can start sending events to Microsoft Conversions API.

Setting up Conversion Goals

Now that you've configured Freshpaint to connect to your UET Tag, you can send events to Microsoft Ads to track specific conversion goals.

Create a conversion goal:

When sending events from Freshpaint to Microsoft Ads, the Freshpaint event name must match the conversion goal name configured in your Microsoft Ads account. For example, if your conversion goal in Microsoft Ads is named Form Submission, the event you send from Freshpaint should also be named Form Submission.

If you'd like to use an existing Freshpaint event that has a different name than your Microsoft Ads conversion goal, you can use a Rename Event Transformation in Freshpaint to align the event name before it's sent to the destination. To do so:

1. Navigate to the Transformations page in Freshpaint.

2. Add a Rename Event Transformation to map your existing event name to match the conversion goal name in Microsoft Ads.

If you are a HIPAA account, you will need to add event properties to the allowlist. If you are not a HIPAA account, you can skip this step.

1. Go to the Microsoft Ads Conversions API configuration page in Freshpaint.

2. Click "Configure" next to "Required Properties" and "Recommended Properties".

3. If you're using the Freshpaint/Microsoft Ads Conversions API integration for ad attribution purposes, we recommend you send the $msclkid property. This property is required in order to see ad attribution data in Microsoft Ads. You can do so by checking the box in the popup:

1. Next, add any other properties you'd like to send to Microsoft Ads to the Advanced: HIPAA Allow List:

Once you've followed these steps, you're ready to start sending events to Microsoft Ads!

Confirm and Validate Events

Confirm and Validate Conversions in Freshpaint

1. Navigate to your site and visit a page that should trigger your event.

2. Trigger your event.

3. Navigate to the Event Verification tool.

4. Select Microsoft Ads Conversions API and verify your event went through.

   • This can take up to 90 seconds.

5. Verify the event is marked as OK or resolve any missing property issues.

Confirm and Validate Conversions in Microsoft Ads

To check whether Microsoft Ads is receiving your events:

1. Log in to your Microsoft Ads account.

2. Navigate to Conversions → UET Tags.

3. Click on your Tag ID to open the tag details page.

4. You should see all events tracked by your UET tag appearing on this page.

Conversions may take up to 24-48 hours to appear in your Microsoft Ads Conversion Goals.