Microsoft Ads Conversions API Reference

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

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

Freshpaint property	Microsoft parameter	Type	Requirement	Description
event_type or $event_type	eventType	string	Required (auto-set	Event type. Accepted values: "pageLoad" or "custom". If $event_type is "pageview", will be converted to "pageLoad". Defaults to "custom" if not specified or invalid.
$current_url or url	eventSourceUrl	string	Required for pageLoad events	The URL of the page where the event took place. Note: In HIPAA Mode, the URL will be redacted by Freshpaint if this field is not added to the allowlist. To send the complete URL to Microsoft, add $current_url to your HIPAA allowlist.

User Data Properties

At least one user identifier must be provided in userData. Options include: anonymousId, externalId, em (email), ph (phone), msclkid, idfa, or gaid.

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

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

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.