📘
This integration is currently in beta. Contact your MetaRouter support team to get started.

What Is Microsoft Ads?

Microsoft Ads is a digital advertising platform that enables businesses to create and manage search, shopping, and audience-based ad campaigns. It provides advanced targeting options, including keyword-based bidding, remarketing, and automated optimizations to improve ad performance. The platform includes tools for budget management, performance tracking, and conversion measurement to help advertisers maximize their return on investment.

Microsoft Ads Conversion API (CAPI) enables advertisers to send web and server-side events directly to Microsoft’s Universal Event Tracking (UET) system. By transmitting data server-to-server, the CAPI improves conversion accuracy and resilience against browser tracking limitations while supporting privacy-compliant measurement.

Product Type: Marketing

Integration Type: Starter Kit & ID Sync

Event Source Type: Web, Mobile Browser, & Mobile App

Event Scope: Full-Funnel Events

Capabilities

Sends conversion and engagement data directly to Microsoft Ads via API.
Preserves attribution accuracy even when cookies or client scripts are blocked.
Supports batch uploads of up to 1000 events per request.
Captures identifiers (msclkid, mid) for cross-session tracking and attribution.
Transmits hashed user identifiers (email, phone) for privacy-safe matching.
Supports page, product, and transaction-level events.

Considerations

Always include msclkid for accurate conversion attribution.
Store msclkid for up to 90 days to preserve click-to-conversion linkage.
Include both IP address and user agent to enhance deduplication accuracy.
Hashed email (em) and phone (ph) values must follow SHA-256 format and normalization.
All events must include an event type of either pageLoad or custom.
Each batch request may include up to 1000 events; invalid data may fail the entire batch.

Limitations

Validation errors (400 or 401) result in all batch events being rejected.

Identity Sync

Sync Available: Yes
Required for Starter Kit: Yes
Prerequisites: Client ID needed
Documentation: Microsoft Ads Sync

Sync Details

The Microsoft Ads sync captures the values of the click ID (msclkid).
The msclkid is essential for conversion attribution and is required by Microsoft Ads for accurate conversion tracking.
Microsoft Ads requires that msclkid only be mapped to your conversion events within the starter kit. Please do not add the click ID to global mapping; otherwise, Microsoft Ads will consider all events a conversion.
The sync generates a mid (pageLoadId) for each page view and attaches it to all related events. Themid is required to properly link events to a session.

Starter Kit Setup Guide

1. Deploy the Microsoft Ads Sync

To collect the sync values (e.g., msclkid, mid), you must implement a Microsoft Ads ID sync. Refer to the following documentation to complete the setup: Microsoft Ads - ID Sync Guide.

2. Gather Credentials

Ask vendor representatives for the following credentials:
- UET Tag ID: Found under Conversion Tracking > UET Tags in your Microsoft Ads account. Once you click on a specific tag, you will find the TAG ID in the breadcrumb area:
- API Token: Obtain from your Microsoft Ads account representative.

3. Add a Microsoft Ads Integration

From the integration library, add a Microsoft Ads integration. Then, fill out the Connection Parameters:

Connection Parameter	Description
`TAG_ID`	Unique Microsoft Ads UET Tag ID used for event tracking.
`API_TOKEN`	Token used to authenticate and authorize API requests.

4. Configure Event Mapping

MetaRouter provides all of the event mappings that Microsoft Ads integrations typically require. You may add custom events, parameters, or mappings in accordance with Microsoft’s API documentation.

5. Deploy to Pipeline

In the Pipelines tab, add your Microsoft Ads integration.
Select the correct integration revision.
Click Add Integration and finalize deployment.

Event Mappings

Global

Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.

Output Key	Description	Expected Input
`eventType` Required	String: Type of event (`pageLoad` or `custom`).	Expression – from `input.type`
`eventTime` Required	Integer: Timestamp in seconds (UTC).	Expression – convert RFC3339 timestamp to epoch
`pageLoadId` * Required	String: UUID linking page load and custom events. * Required for custom events that follow a `pageLoad`.	`context.providers.microsoftAds.mid`
`eventSourceUrl` * Required	String: Page URL where the event occurred. Required for `pageLoad` events.	`context.page.url`
`userData.msclkid` Required	String: Microsoft Click ID.	`context.providers.microsoftAds.msclkid`
`userData.clientIpAddress` Required	String: IP address of the user.	`context.ip`
`userData.clientUserAgent` Required	String: Browser user agent string.	`context.userAgent`
`userData.anonymousId` Recommended	String: Anonymous visitor ID.	`anonymousId`
`eventName` Recommended	String: Event name or fallback to event type.	Expression – `input.event or input.type`
`eventId`	String: Unique event ID for deduplication.	`messageId`
`pageTitle`	String: Title of the webpage.	`context.page.title`
`referrerUrl`	String: URL of the referring page.	`context.page.referrer`
`userData.externalId`	String: Authenticated user ID.	`userId`
`userData.em`	String: SHA-256 hashed normalized email address.	Expression – hash `traits.email`
`userData.ph`	String: SHA-256 hashed normalized phone number.	Expression – hash `traits.phone`

Event Specific

Page

Output Key	Description	Expected Input
`customData.eventLabel` Recommended	String: Hardcoded page label. Optional field providing a human-readable description for reporting and debugging; helps distinguish similar events that share the same `eventName`.	Enrichment – `'Lorem ipsum'`
`customData.pageType`	String: `home` when path is `/`, otherwise `other`.	Expression – from `context.page.path`

Products Searched

Output Key	Description	Expected Input
`customData.pageType`	String: Indicates search results page.	Enrichment – `'searchresults'`
`customData.eventCategory`	String: Event category for search actions.	Enrichment – `'search'`
`customData.searchTerm`	String: Search query entered by user.	`properties.query`

Product List Viewed

Output Key	Description	Expected Input
`customData.pageType`	String: Indicates category listing page.	Enrichment – `'category'`
`customData.ecommCategory`	String: Category viewed by user.	`properties.category`
`customData.itemIds`	Array: Product IDs or SKUs listed.	Expression – map `properties.products`
`customData.items`	Array: Product list `{id,name,price,quantity}`.	Expression – map `properties.products`

Product Clicked

Output Key	Description	Expected Input
`customData.pageType`	String: Product context.	Enrichment – `'product'`
`customData.ecommCategory`	String: Category of clicked product.	`properties.category`
`customData.itemIds`	Array: Clicked product ID.	Expression – from `properties.product_id or sku`
`customData.items`	Array: Details of clicked product.	Expression – build from `properties`

Product Viewed

Output Key	Description	Expected Input
`customData.pageType`	String: Indicates product view page.	Enrichment – `'product'`
`customData.ecommCategory`	String: Product category viewed.	`properties.category`
`customData.itemIds`	Array: Product IDs viewed.	Expression – from `properties.product_id or sku`
`customData.items`	Array: Product details viewed.	Expression – build from `properties`

Product Added

Output Key	Description	Expected Input
`customData.pageType`	String: Indicates add-to-cart event.	Enrichment – `'product'`
`customData.ecommCategory`	String: Product category added.	`properties.category`
`customData.itemIds`	Array: Added product IDs.	Expression – from `properties.product_id or sku`
`customData.items`	Array: Details of added product(s).	Expression – build from `properties`
`customData.value`	Float: Total value of added items.	Expression – `TOTAL_VALUE(properties)`
`customData.ecommTotalValue`	Float: Event total value.	Expression – `TOTAL_VALUE(properties)`
`customData.currency`	String: ISO 4217 currency code.	`properties.currency` (uppercase, default USD)

Product Removed

Output Key	Description	Expected Input
`customData.pageType`	String: Product context for removal.	Enrichment – `'product'`
`customData.ecommCategory`	String: Product category removed.	`properties.category`
`customData.itemIds`	Array: Removed product IDs.	Expression – from `properties.product_id or sku`
`customData.items`	Array: Details of removed product(s).	Expression – build from `properties`
`customData.value`	Float: Value removed from cart.	Expression – `TOTAL_VALUE(properties)`
`customData.ecommTotalValue`	Float: Total cart value after removal.	Expression – `TOTAL_VALUE(properties)`
`customData.currency`	String: ISO 4217 currency code.	`properties.currency` (uppercase, default USD)

Cart Viewed

Output Key	Description	Expected Input
`customData.pageType`	String: Indicates cart page view.	Enrichment – `'cart'`
`customData.itemIds`	Array: Product IDs in cart.	Expression – map `properties.products`
`customData.items`	Array: Item details `{id,name,price,quantity}`.	Expression – map `properties.products`
`customData.value`	Float: Total cart value.	Expression – `TOTAL_VALUE(properties.products)`
`customData.ecommTotalValue`	Float: Total cart value (duplicate for reporting).	Expression – `TOTAL_VALUE(properties.products)`
`customData.currency`	String: ISO 4217 currency code.	`properties.currency` (uppercase, default USD)

Order Completed

Output Key	Description	Expected Input
`customData.transactionId` Required	String: Unique order ID.	`properties.order_id`
`customData.pageType`	String: Indicates purchase confirmation.	Enrichment – `'purchase'`
`customData.itemIds`	Array: Purchased product IDs.	Expression – map `properties.products`
`customData.items`	Array: Purchased item details.	Expression – map `properties.products`
`customData.value`	Float: Total order value.	Expression – `TOTAL_VALUE(properties.products)`
`customData.ecommTotalValue`	Float: Total order value (duplicate for reporting).	Expression – `TOTAL_VALUE(properties.products)`
`customData.currency`	String: ISO 4217 currency code.	`properties.currency` (uppercase, default USD)

Required & Recommended Identifiers

These identifiers must be mapped to Microsoft Ads in order for successful user matching to occur. Without these IDs, any events sent to Microsoft Ads may not be accurately reflected in reporting.

Attribute	Example	Sync Injector Required?
`msclkid` Required	dd4afcccb1c9a4cad9544dd7e5006	Yes
`mid` Required	bcf3000b-65fa-4cd2-808a-8a6cf2b1d0a5	Yes
`anonymousId`	b171a9b06ce011ecafcd1b209be8601b	Yes
`externalId`	111222	No
`email_hash` Recommended	e1a2b3c4d5e6f7...	No
`phone_hash` Recommended	c59475d96e9f01d7...	No

Integration Validation

Use the UET Tag Dashboard in your Microsoft Advertising account to verify that server-side events are being received successfully. You can also access UET reports within the platform to review event delivery, troubleshoot discrepancies, and validate conversion tracking.

Additional Microsoft Ads Documentation