> 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/miscrosoft-ads-conversions-api-early-access/miscrosoft-ads-conversions-api-reference.md).

# Microsoft Ads Conversions API Reference

{% 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](/integrations/google-tag-manager-integration.md)
* 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.
* 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>

This is a reference document for the Microsoft Ads Conversions API destination. For information on how to set up this integration, see the Microsoft Ads Conversions API Quick Start Guide.

## Events

### Required Properties

<table><thead><tr><th width="155.3203125">Freshpaint property</th><th>Microsoft parameter</th><th>Type</th><th>Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>event_type</code> or <code>$event_type</code></td><td><code>eventType</code></td><td>string</td><td>Required (auto-set)</td><td>Event type. Accepted values: "pageLoad" or "custom".<br>If <code>$event_type</code> is "pageview", will be converted to "pageLoad". Defaults to "custom" if not specified or invalid.</td></tr></tbody></table>

#### Event Source URL

{% hint style="warning" %}
If your Freshpaint account is set up in [HIPAA Mode](https://documentation.freshpaint.io/readme/hipaa-mode), the URL will be redacted by default because it may contain PHI. For example, if the URL of the event is `https://example.com/heart-conditions#treatments?user=alice` then Freshpaint will send `https://example.com/url-redacted-by-freshpaint`. To send the complete URL to Microsoft, add the Built-in `URL` (`$current_url) property` to your HIPAA allowlist.
{% endhint %}

### User Data Properties

{% hint style="warning" %}
At least one user identifier must be provided in userData. Options include: `anonymousId`, `externalId`, `em` (email), `ph` (phone), `msclkid`, `idfa`, or `gaid`.
{% endhint %}

| Freshpaint property                                            | Microsoft CAPI parameter | Type            | Requirement           | Description                                                                                                        |
| -------------------------------------------------------------- | ------------------------ | --------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `anonymous_id` or `$device_id` if `anonymous_id` not provided. | `anonymousId`            | string          | At least one required | Anonymous identifier for the user. Falls back to `$device_id` as UUID                                              |
| `email`                                                        | `em`                     | string (hashed) | At least one required | The email of the user.                                                                                             |
| `phone`                                                        | `ph`                     | string (hashed) | At least one required | The phone number of the user.                                                                                      |
| `external_id`                                                  | `externalId`             | string          | At least one required | Your internal user ID for the customer.                                                                            |
| `$user_agent`                                                  | `clientUserAgent`        | string          | Recommended           | The user agent of the browser where the event occurred.                                                            |
| `$ip`                                                          | `clientIpAddress`        | string          | Recommended           | IP address from the device that sent the conversion event.                                                         |
| `$msclkid`                                                     | `msclkid`                | string          | Recommended           | Microsoft Click ID. Retrieved from the `msclkid` query parameter in the URL. Important for conversion attribution. |
| `idfa`                                                         | `idfa`                   | string          | Recommended           | iOS Identifier for Advertisers (IDFA) for mobile app events.                                                       |
| `gaid`                                                         | `gaid`                   | string          | Recommended           | Google Advertising ID (GAID) for Android mobile app events.                                                        |

### **Custom Data**

<table><thead><tr><th width="149">Freshpaint property</th><th>Microsoft CAPI parameter</th><th>Type</th><th>Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>event_category</code></td><td><code>eventCategory</code></td><td>string</td><td>Optional</td><td>Event category for custom conversion goals. Example: <code>my_category</code></td></tr><tr><td><code>event_label</code></td><td><code>eventLabel</code></td><td>string</td><td>Optional</td><td>Event label for custom conversion goals. Example: <code>my_label</code></td></tr><tr><td><code>event_value</code></td><td><code>eventValue</code></td><td>float</td><td>Optional</td><td>Event value for custom conversion goals. Example: <code>123.45</code></td></tr><tr><td><code>search_term</code></td><td><code>searchTerm</code></td><td>string</td><td>Optional</td><td>Search query used by the user on a search results page. Example: <code>Wall clocks</code></td></tr><tr><td><code>transaction_id</code></td><td><code>transactionId</code></td><td>string</td><td>Optional</td><td>Unique ID associated with the transaction. Recommended for singular events like a purchase. Example: <code>txn12345</code></td></tr><tr><td><code>value</code></td><td><code>value</code></td><td>float</td><td>Optional</td><td>Revenue value to report variable revenue for goals. Example: <code>123.45</code></td></tr><tr><td><code>currency</code></td><td><code>currency</code></td><td>string</td><td>Optional</td><td>Revenue currency in 3-digit ISO 4217 format. Freshpaint automatically converts to uppercase. Example: <code>USD</code> or <code>EUR</code></td></tr><tr><td><code>page_type</code></td><td><code>pageType</code></td><td>string</td><td>Optional</td><td>Type of page. Accepted values: <code>cart</code>, <code>category</code>, <code>home</code>, <code>other</code>, <code>product</code>, <code>purchase</code>, <code>searchresults</code></td></tr><tr><td><code>ecomm_total_value</code></td><td><code>ecommTotalValue</code></td><td>float</td><td>Optional</td><td>Total value of the cart or purchase. Example: <code>123.45</code></td></tr><tr><td><code>ecomm_category</code></td><td><code>ecommCategory</code></td><td>string</td><td>Optional</td><td>Category ID. Example: <code>1234</code></td></tr><tr><td><code>item_ids</code></td><td><code>itemIds</code></td><td>array of strings</td><td>Optional</td><td>Array of product IDs. Example: <code>["prod1", "prod2"]</code></td></tr></tbody></table>

### **Hotel Data**

| Freshpaint property | Microsoft CAPI parameter | Type            | Requirement | Description                                                                                                     |
| ------------------- | ------------------------ | --------------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
| `total_price`       | totalPrice               | integer         | Optional    | Total price of the booking, including taxes and fees. Example: `188`                                            |
| `base_price`        | basePrice                | number($double) | Optional    | Price of the booking, not including taxes and fees. Example: `165`                                              |
| `checkin_date`      | checkinDate              | string          | Optional    | Check-in date in the format `YYYY-MM-DD`. Example: `2018-10-27`                                                 |
| `checkout_date`     | checkoutDate             | string          | Optional    | Check-out date in the format `YYYY-MM-DD`. Not required if `length_of_stay` is specified. Example: `2018-10-31` |
| `length_of_stay`    | lengthOfStay             | integer         | Optional    | Number of nights the booking is for. Not required if `checkout_date` is specified. Example: `4`                 |
| `partner_hotel_id`  | partnerHotelId           | string          | Optional    | ID used to identify the hotel in your property feed. Example: `example_hotel`                                   |
| `booking_href`      | bookingHref              | string          | Optional    | Encrypted or obfuscated booking reference number. Example: `X2N5531APZ`                                         |

## Considerations

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

## Troubleshooting

**Conversion events not showing up in Microsoft Ads Dashboard**: For an event to show up as a conversion event it must have a `msclkid` property. You can validate that events going to Microsoft have this `msclkid` property using the [Freshpaint Liveview](https://documentation.freshpaint.io/events/liveview).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/miscrosoft-ads-conversions-api-early-access/miscrosoft-ads-conversions-api-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.