# 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](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>

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).