Microsoft CAPI
The Microsoft Conversions API (CAPI) is a server-side integration that sends event data directly from Chord CDP to Microsoft Advertising's servers. Unlike the Bing Ads UET Tag (which runs in the browser), the Conversions API operates in cloud mode — events are sent server-to-server, making them immune to ad blockers and browser tracking restrictions.
Microsoft recommends using the Conversions API alongside the UET Tag for maximum data coverage. When both are configured, Microsoft automatically deduplicates events using the eventId field.
Use this destination if:
- You run paid media through Microsoft Advertising
- You want improved signal reliability independent of browser limitations or ad blockers
- You want to support Microsoft's automated bidding and optimization with high-quality server-side event data
Getting Started
This is a cloud-mode destination. You will need:
- UET Tag ID — found in your Microsoft Ads dashboard under Conversion tracking > UET tags. We recommend creating a dedicated tag for the Conversions API
- Access Token — select "Use Conversions API" on your UET tag in the Microsoft Ads dashboard to generate a token. Contact your Microsoft account manager if this option is not available
- Site URL — your storefront URL, e.g. https://www.example.com.
- Optional in general, but required for back-end (server-side) connections: Microsoft rejects events with an empty eventSourceUrl, and server-side events carry no page URL, so this value is used as the fallback. Browser connections don't need it (the event's own page URL is used). Without it, back-end purchase events are rejected with a 400 ValidationError.
Connecting to the Microsoft Conversions API CDP Destination
- Log into the Chord data platform.
- Navigate to the CDP.
- Click the "Add" button next to Destinations.
- Select Microsoft Conversions API from the destination catalog.
- Enter the destination name, UET Tag ID, and Access Token.
- Click "Create" to connect.
Event Architecture
Microsoft CAPI requires a pageLoad event to establish page context. Chord CDP handles this automatically:
- Page events send a single pageLoad event
- Track events send a pageLoad + custom event pair, linked by a shared page load ID
This means Microsoft receives the page context needed for accurate attribution without any additional configuration.
Events
Event Mapping
By default the event action (eventName) sent to Microsoft is the Chord event's own name (e.g. Order Completed). This matches the Bing UET device-mode pixel, which sends the raw event name, so the two surfaces can share a single conversion goal. Recognized commerce events additionally get a pageType:
Chord Event | Page Type |
|---|---|
Product Viewed | product |
Products Searched | searchresults |
Product Added | cart |
Checkout Started | cart |
Order Completed | purchase |
Order Placed | purchase |
(other track events) | (none) |
Page and track events are forwarded. Identify and screen events are ignored.
Overriding the event action
The Event Mapping config setting overrides the event action for specific events. Unmapped events keep the raw-name default, so this is purely additive.
Use it when a conversion goal expects a different action string — for example a customer who prefers snake_case, or a goal keyed on order_completed:
{ "Order Completed": "order_completed", "Product Added": "product_added" }Goal matching in Microsoft Ads is case-sensitive, so the value must match the goal's Event Action rule exactly.
Common Event Fields
These fields are included on every event sent to Microsoft.
Microsoft Field | Chord Source (Priority Order) | Notes |
|---|---|---|
eventType | (derived) | pageLoad or custom |
eventId | messageId + suffix | -pl for page load, -ce for custom event |
eventTime | timestamp | Converted to Unix seconds |
eventSourceUrl | page.url > context.page.url > properties.url | |
referrerUrl | page.referrer > context.page.referrer | |
pageTitle | page.title > context.page.title > properties.title | |
User Data
PII fields are SHA256-hashed using Microsoft-specific normalization rules before sending.
Microsoft Field | Chord Source (Priority Order) | Notes |
|---|---|---|
em (email) | properties.email > context.traits.email | Microsoft-specific hashing: dots removed from user portion, +aliases stripped, lowercased, SHA256 |
ph (phone) | properties.phone > context.traits.phone | Validated, normalized to E.164 format, SHA256-hashed. Invalid phones are silently dropped |
externalId | userId | SHA256-hashed (lowercased) |
anonymousId | anonymousId | Not hashed — Microsoft uses as guest UUID |
clientUserAgent | context.userAgent | Not hashed |
clientIpAddress | context.ip | Not hashed |
msclkid | URL parameter msclkid > properties.msclkid > integrations["Microsoft CAPI"].msclkid | Microsoft click ID for attribution |
Phone Validation
Phone numbers are validated before hashing. The following are silently rejected:
- Common junk values: n/a, na, undefined, null, none, unknown, test
- Numbers with fewer than 7 digits
- All-repeated-digit numbers (e.g., 1111111)
Custom Data (Track Events)
The custom event in each pair includes conversion properties:
Microsoft Field | Chord Source (Priority Order) | Notes |
|---|---|---|
value | properties.revenue > properties.total > properties.price | First numeric value found; Order Completed has no properties.value field |
currency | properties.currency | |
transactionId | properties.orderId / properties.order_id | For deduplication |
searchTerm | properties.query > properties.search_term | |
eventCategory | properties.category | |
eventLabel | properties.label | |
pageType | (from event mapping table) | E.g., product, cart, purchase |
items | See Item Attributes below | |
Item Attributes
For single-product events (Product Viewed, Product Added), item data is extracted from top-level properties:
Microsoft Field | Chord Source |
|---|---|
id | properties.sku > properties.product_id > properties.id |
quantity | properties.quantity |
price | properties.price |
name | properties.name |
For multi-product events (Checkout Started, Order Completed, Order Placed), items come from the properties.products array:
Microsoft Field | Chord Source |
|---|---|
id | products[].sku > products[].product_id > products[].id |
quantity | products[].quantity |
price | products[].price |
name | products[].name |
Required Fields
For purchase events (Order Completed / Order Placed) to be accepted by Microsoft, the following fields must be present:
- Event name and event time (populated automatically by Chord CDP)
- properties.currency
- properties.value, properties.revenue, or properties.total (at least one)
- properties.order_id or properties.orderId
- At least one user identifier: properties.email, properties.phone, or msclkid (from URL parameter)
Testing and Validation
After connecting the destination:
- Use Microsoft Ads event diagnostics (in the UET tags section of your dashboard) to confirm events are being received
- Verify match rates — higher match rates indicate user identifiers (email, phone, msclkid) are being sent correctly
- Confirm revenue values and order counts align with your expectations
If discrepancies appear:
- Confirm msclkid is being captured in your page URLs (Microsoft appends this to ad click-through URLs)
- Ensure required fields listed above are populated in your events
- Check that your access token has not expired — regenerate in the Microsoft Ads dashboard if needed
Property Mappings
Use custom property mappings if the default field resolution does not match your data model:
Destination Path | Description |
|---|---|
properties.email | Email for enhanced conversions |
properties.phone | Phone for enhanced conversions (E.164 format preferred) |
properties.value | Primary conversion value |
properties.revenue | Fallback conversion value (subtotal) |
properties.currency | Currency code (e.g., USD) |
properties.order_id | Transaction ID for deduplication |
properties.products[].sku | Product item IDs |
properties.products[].price | Per-item price |
properties.products[].quantity | Per-item quantity |
properties.products[].name | Product display name |
Updated 12 Mar 2026