# Microsoft Ads Conversions API Quick Start Guide

{% hint style="warning" %}
The Microsoft Ads Conversions API destination is currently in Early Access. Please contact <support@freshpaint.io> for more information about this integration.
{% endhint %}

## Destination Info

* Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls
* Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode)
* Supports forwarding from the [Google Tag Manager Integration](https://documentation.freshpaint.io/integrations/google-tag-manager-integration)
* Refer to this destination as **Microsoft Ads Conversions API** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-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. &#x20;
* Connection Modes:

<table><thead><tr><th align="right"> </th><th data-type="checkbox">Client-side</th><th data-type="checkbox">Server-side</th></tr></thead><tbody><tr><td align="right">Web</td><td>false</td><td>true</td></tr><tr><td align="right">Mobile</td><td>false</td><td>true</td></tr><tr><td align="right">Server</td><td>false</td><td>true</td></tr></tbody></table>

## 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](https://documentation.freshpaint.io/readme/guides/quickstart/installing-freshpaint).

### **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**

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FPj8YWwnjTKcVPAXajJdH%2FScreenshot%202026-02-19%20at%2012.40.11%E2%80%AFPM.png?alt=media&#x26;token=ef41dac2-8369-421a-867c-9bcf3bd81210" alt=""><figcaption></figcaption></figure>

<br>

2. Click **+ Create** to create a new tag.

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2F8SSdNSLpKBwWEWQM0wvs%2FScreenshot%202026-02-19%20at%2012.41.42%E2%80%AFPM.png?alt=media&#x26;token=a2eb7b2d-0022-441d-8e7f-4ec3517b8bc1" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2Fogz1HRdFAOFwVoMtkc5p%2FScreenshot%202026-02-19%20at%2012.43.53%E2%80%AFPM.png?alt=media&#x26;token=29d00ba5-b2ce-479d-ab64-92e7e9d1bb4c" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FvV0r5L6Ep1yyJ4Unrmz2%2FScreenshot%202026-02-19%20at%2012.46.03%E2%80%AFPM.png?alt=media&#x26;token=9ec0d06f-17e1-451d-bc1f-d9d5ce718bfc" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
The **Use Conversions API** option is not available by default. To enable this feature, contact your Microsoft Account Manager.
{% endhint %}

5. Copy the token on the next page.

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FfCNeioXX5lwmgNz0FsKi%2Fimage.png?alt=media&#x26;token=c9a0d4ee-afda-4bd6-8d18-a9858636698c" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FnrrP0F7SNPq9tkQ4yfUm%2Fimage.png?alt=media&#x26;token=85326450-9e24-438c-be95-92991a5dc7d5" alt=""><figcaption></figcaption></figure>

### Enable the Freshpaint Microsoft Conversions API destination <a href="#enable-the-freshpaint-snapchat-destination" id="enable-the-freshpaint-snapchat-destination"></a>

1. Navigate to the [Freshpaint Destinations page](https://app.freshpaint.io/destinations/catalog).
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.](https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/miscrosoft-ads-conversions-api-early-access/miscrosoft-ads-conversions-api-reference)
5. Enable Microsoft Conversions API.

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

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FjqbnwuPdbMEafaXAXg3M%2FScreenshot%202026-02-19%20at%201.05.00%E2%80%AFPM.png?alt=media&#x26;token=47e7a4fa-27c0-48e4-9ae4-384af05ae7c0" alt=""><figcaption></figcaption></figure>

## 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](https://app.freshpaint.io/transformations) in Freshpaint.
2. Add a Rename Event Transformation to map your existing event name to match the conversion goal name in Microsoft Ads.

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FSUk8HvxSte2RJLeMFZq7%2FScreenshot%202026-03-05%20at%2011.43.36%E2%80%AFAM.png?alt=media&#x26;token=197afc5d-7834-412e-af3e-c9447b06bbf2" alt=""><figcaption></figcaption></figure>

### 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".&#x20;
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:&#x20;

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FX3PjIZiYbwOiEEzfb4gI%2FScreenshot%202026-02-19%20at%201.43.10%E2%80%AFPM.png?alt=media&#x26;token=e5996dec-79ec-4d9e-b47c-4159e00e0d9b" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FPn3krrviNXawHuzc8Z8l%2FScreenshot%202026-02-19%20at%201.46.03%E2%80%AFPM.png?alt=media&#x26;token=2d1596cc-cdd0-47a3-b80e-110ca14fe868" alt=""><figcaption></figcaption></figure>

&#x20;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](https://app.freshpaint.io/event-verification).
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.

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FS1bqYWwhbIOtiy2NzFpi%2FScreenshot%202026-02-19%20at%201.38.29%E2%80%AFPM.png?alt=media&#x26;token=6f986dee-8455-44e3-ab9d-6fec3d81f42a" alt=""><figcaption></figcaption></figure>

### **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.

{% hint style="info" %}
Conversions may take up to 24-48 hours to appear in your Microsoft Ads Conversion Goals.
{% endhint %}