Microsoft UET Conversion API Connector Setup Guide
This article describes how to set up the Microsoft UET Conversion API connector.
This connector is not currently available in the connector marketplace. Using the Microsoft UET Conversions connector requires support from both Tealium and the Microsoft account managers. To use this connector, contact your Tealium account manager.
Overview
Advertisers use the Microsoft UET Conversion API to send web and offline conversion events directly to Microsoft Advertising. This connector enables enhanced attribution, signal resiliency, and privacy-focused measurement.
You can use the Microsoft UET Conversion API as a standalone integration or together with the Microsoft UET tag. In a dual-delivery setup, the UET tag sends real-time, client-side events, while the conversion API delivers events reliably in cases of cookie loss, JavaScript restrictions, or offline conversions. Using both methods provides redundancy and improves coverage throughout the customer journey.
Batch Limits
This connector uses batched requests to support high-volume data transfers to the vendor. For more information, see Batched Actions. Requests are queued until one of the following thresholds is met or the profile is published:
- Max number of requests: 1,000
- Max time since oldest request: 10 minutes
- Max size of requests: 1 MB
Prerequisites
- Microsoft Ads Account: Active Microsoft Advertising account with UET tag and CAPI access.
- UET Tag ID: Microsoft requires a UET tag ID for attribution and audience association, even if using only server-side tracking through Tealium for online or offline conversions. Find the UET tag ID in your Microsoft Ads platform. Use an existing tag or provision a new UET tag ID as needed.
- Access Token: Get the token from your Microsoft Account Manager.
- Conversion Goal: To ensure Microsoft can attribute CAPI events correctly, create at least one conversion goal tied to your UET tag.
- Go to Tools > Conversion Goals.
- Click + New Conversion Goal.
- Choose a goal type (for example, purchase, lead, booking).
- Associate it with your UET tag ID.
Configuration
To add the connector, go to the Connector Marketplace and add a new connector. For general instructions on how to add a connector, see About Connectors.
After adding the connector, configure the following settings:
- UET tagID
You can use your existing tag or provision a new UET tag ID in your Microsoft Advertising account. - Access Token
The access token for your Microsoft Advertising account.
Offline Conversions
To process offline and store events through the Microsoft UET Conversions connector, configure the connector to include the required parameters.
For online conversions, attribution typically occurs in real time. For offline conversions, Microsoft supports backdated events up to 90 days old. Attribution accuracy improves when events are sent closer to real time.
Prerequisites
- Enable Offline Conversion Import: This must be enabled in Microsoft Ads to allow it to ingest CAPI events sent from Tealium.
- Go to Tools > Offline Conversions.
- Select Import Conversions.
- Select Microsoft (Offline conversions via API).
- Associate the conversion goal with the UET tag: This must be enabled to ensure Microsoft can attribute conversions to ad interactions.
- Go to Tools > Conversion Goals.
- Click + New Conversion Goal.
- Select a goal type relevant to offline events (for example, In-Store Purchase, Phone Booking, Loan Application).
- Under Goal Source, select Offline Conversions (Import via file or API).
- Associate the goal with your existing UET tag ID.
- Ensure that the UET tag ID exists: Ensure that the UET tag ID referenced in your goal exists in Microsoft Ads, even if the tag itself is not deployed.
- Pass click IDs or hashed PII with the event: This lets Microsoft perform matching.
Best Practices
- Persist the click ID: The Microsoft Click ID (
msclkid
) is critical to conversion tracking. When auto-tagging is enabled in Microsoft Ads, this identifier is appended as a query parameter on the landing page URL after a user clicks an ad. Persisting the click ID with a Persist Data Values extension ensures that it is available for server-side use. Map the cookie attribute server-side. Without the click ID, Microsoft may not be able to link the conversion back to the originating ad click, resulting in lost attribution and under-optimized bidding. - Every click fires a page load event: Every page view or single-page application (SPA) navigation must fire one page load event. You may also fire one or more custom events. Each custom event links to a page load event through the
pageLoadId
parameter. - Enable Microsoft ID Beacon Sync: Enable Microsoft ID Beacon Sync in the Microsoft UET tag to improve identity resolution and remarketing performance. This feature supports identity stitching across devices and improves the ability to match online behavior to offline conversions.
- Consent granted by default: By default, Microsoft processes all events as consent state being granted. If you need to use explicit consent signals, you can use the parameter
adStorageConsent
with the following options:G
= granted.D
= denied. Denied events will not be used for any ad purposes (including conversion attribution and retargeting).
- Strict phone and email formats: When using SHA256 hashed PII, follow these formatting rules:
- Format phone numbers according to the E.164 standard.
- For email addresses:
- Remove whitespaces from the beginning and end of the email address.
- Ensure the text is in lower case.
- Remove everything between
+
and@
(for example,user+withplus@example.com
becomesuser@example.com
). - Remove periods before
@
(for example,us.er@example.com
becomesuser@example.com
). - Ensure email addresses contain the
@
sign. - Remove any spaces.
- Ensure there is a period after
@
, such as.com
. - Ensure it doesn’t start or end with a period.
- Remove any accents (for example,
à
).
Frequently asked questions
- Can I use the UET Conversion API without the UET tag?
Yes. However, it is not recommended. While the UET Conversion API can work independently, Microsoft strongly recommends implementing both the UET tag and UET CAPI. Using both methods improves attribution accuracy by recovering from signal loss. - Can I send the same conversion in the tag and connector?
Yes. It is not required but highly recommended. Microsoft supports deduplication to prevent over-counting. Sending conversions through both channels ensures resiliency; if one fails, the other still attributes the event correctly. - Can I send a conversion without a click ID?
Only when necessary or unavailable. The click ID is the most accurate way to attribute a conversion to a Microsoft/Bing Ad click. While sending hashed PII as a fallback is possible, the conversion match quality may be reduced, especially for Smart Bidding and reporting. - Can I use this connector for lead forms or phone calls?
Yes. Send lead form completions, pre-qualification submissions, and call center events using this connector. This is ideal for finance, auto, and travel verticals with high offline conversion volume.
Troubleshooting
Use the Trace tool to monitor event flow in EventStream and AudienceStream. You can also enable the “Test Mode” toggle or send events to a staging instance if configured in your Microsoft Ads account.
Actions
Action Name | AudienceStream | EventStream |
---|---|---|
Send Conversion Event | ✓ | ✓ |
Send Conversion Event (Batched) | ✓ | ✓ |
Enter a name for the action and select the Action Type.
The following section describes how to set up parameters and options for each action.
Send Conversion Event
Parameters
Event Type
Parameter | Description |
---|---|
Event type | The event type. Available options are Page Load or Custom . |
Conversion Data
Parameter | Description |
---|---|
Event ID | Unique ID of the event. Event ID is required for deduplication. |
Event Name | Event action for custom conversion goals, if used. |
Event Time | Timestamp of the event (UNIX epoch time UTC) in seconds. The connector automatically maps this parameter when it appears in the event. If no value is set, the connector uses the current time. |
Event Source URL | URL of the page, used for external destination URL goals. The connector automatically maps this parameter when it appears in the event. If you map an attribute, it overrides this value. |
Ad Storage Consent | For consent signals, use G for granted and D for denied. |
Page Load ID | Page load ID that links to one or more custom events from the same page. This parameter must be formatted as a v4 UUID. |
Referrer URL | Referrer of the page, used for external “referral” remarketing lists. |
Page Title | Page title (for example, document.title ). |
Keywords | Page keywords (SEO meta keywords). |
User Data
Parameter | Description |
---|---|
Client User Agent | User agent header from the browser of the end user. |
Anonymous ID | Guest user anonymous ID, also used for ID sync. Prefer (not required) a v1 UUID. |
External ID | Authenticated user ID (anonymized) if user is logged in. Also used for ID sync. |
Email Address (already SHA256 hashed) | Provide an email address which has been already whitespace trimmed, lowercased and SHA256 hashed. |
Email Address (apply SHA256 hash) | Provide a plain text email address and the connector whitespace trims, lowercases, and hashes this value using SHA256 hash. |
Phone Number (already SHA256 hashed) | Provide a phone number which has been already whitespace trimmed, lowercased and SHA256 hashed. |
Phone Number (apply SHA256 hash) | Provide a plain text phone number and the connector whitespace trims, lowercases, and hashes this value using SHA256 hash. |
Client IP Address | The IPv4 or IPv6 address of the user. |
Microsoft Click ID | The click ID is used to assist the connector in attributing conversions accurately to clicks. |
GAID | For Android devices, the Google advertising ID. |
IDFA | For iOS devices ID, the Apple device ID. |
Custom Data
Parameter | Description |
---|---|
Event Category | Event category for custom conversion goals, if used. The connector automatically maps this parameter when it appears in the event. |
Event Label | Event label for custom conversion goals, if used. |
Event Value | Event value (float) for custom conversion goals, if used. The connector automatically maps this parameter when it appears in the event. |
Search Term | Search query used by the user for a search results page, optional. |
Transaction ID | Unique ID associated with this, optional but recommended for singular events like a purchase. The connector automatically maps this parameter when it appears in the event. |
Value | Revenue value (float) to report variable revenue for goals, if used. The connector automatically maps this parameter when it appears in the event. |
Currency | The revenue currency in 3-digit ISO 4217 format, if used. The connector automatically maps this parameter when it appears in the event. |
Item Data
Parameter | Description |
---|---|
ID | Item ID. The connector automatically maps this parameter when it appears in the event. |
Quantity | Item quantity. The connector automatically maps this parameter when it appears in the event. |
Price | Item price after discounts. The connector automatically maps this parameter when it appears in the event. |
Name | Item name. The connector automatically maps this parameter when it appears in the event. |
Vertical Specific Type
Parameter | Description |
---|---|
Select Vertical Specific Type | The vertical type for the event. Accepted values are Retail and Hotel . |
Vertical Specific Parameters if Vertical Specific Type is empty
If no Select Vertical Specific Type is selected, manually map attributes to vendor parameters.
Vertical Specific Parameters if Vertical Specific Type is Hotel
Parameter | Description |
---|---|
Total Price | Total price of the booking, including taxes and fees. |
Base Price | Price of the booking, not including taxes and fees. |
Checkin Date | Check-in date in YYYY-MM-DD format. |
Checkout Date | Check-out date in YYYY-MM-DD format. This value is not required if Length of Stay is specified. |
Length of Stay | Number of nights the booking is for. This value is not required if Checkout Date is specified. |
Partner Hotel ID | The ID that you used to identify the hotel in your property feed. |
Booking Href | Encrypted or obfuscated booking reference number. |
Vertical Specific Parameters if Vertical Specific Type is Retail
Parameter | Description |
---|---|
Item Ids | Comma-separated list of product IDs. |
Page Type | The page type. This value can be one of the following: cart , category , home , other , product , purchase , or searchresults . |
Ecomm Total Value | Total value of the cart or purchase. |
Ecomm Category | The category ID. |
Automatic Deduplication
Parameter | Description |
---|---|
Tealium iQ Tag ID | When the Tealium iQ tag ID is provided, the connector automatically looks for your event ID value that is sent from Tealium iQ. |
Disable Automapping
Parameter | Description |
---|---|
Disable Automapping | If Automapping is disabled, automatically mapped parameters are not sent to the vendor by default. |
Send Conversion Event (Batched)
This action uses the same parameters and mapping options as the Send Conversion Event action. For more information, see Send Conversion Event.
This page was last updated: October 22, 2025