# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/miscrosoft-ads-conversions-api-early-access/miscrosoft-ads-conversions-api-quick-start-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.