Microsoft Ads CAPI

Datafly Signal delivers conversion events to Microsoft Advertising server-to-server using the Conversions API (formerly Bing Ads). This enables accurate conversion tracking for Bing, Edge, and Microsoft Audience Network campaigns without depending on the UET tag client-side script.

Prerequisites

Before configuring Microsoft Ads CAPI in Signal, you need a Microsoft Advertising account, a UET tag, conversion goals, and an OAuth access token. Follow the steps below to set everything up.

Configure in Signal

Now that you have your Customer ID, Account ID, UET Tag ID, and access token, configure the integration in Signal.

Configuration Fields

Management UI Setup

1. Go to Integrations > Add Integration > Microsoft Ads CAPI.
2. Enter your customer_id, account_id, and uet_tag_id.
3. Enter your access_token (and optionally refresh_token with OAuth credentials).
4. Select consent categories (typically advertising).
5. Click Save.

Management API Setup

curl -X POST http://localhost:8084/v1/admin/integrations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_abc123",
    "vendor": "microsoft_ads",
    "name": "Microsoft Ads CAPI",
    "enabled": true,
    "config": {
      "customer_id": "123456789",
      "account_id": "987654321",
      "access_token": "your_access_token",
      "uet_tag_id": "12345678"
    },
    "consent_categories": ["advertising"]
  }'

API Endpoint

POST https://bingads.microsoft.com/api/v13/offline-conversions

Events are sent as JSON with authentication via the Authorization: Bearer header and the DeveloperToken header.

Identity Signals

Microsoft Ads uses multiple identity signals to match server events to ad clicks and user sessions.

Automatic Signals

These are sent automatically by Signal — no configuration needed:

When a user clicks a Microsoft ad, the msclkid parameter is appended to the landing page URL:

https://example.com/landing?msclkid=abc123def456ghi789

Datafly.js automatically captures the msclkid from the URL and persists it as a first-party cookie for the duration of the attribution window.

User-Provided Signals (Hashed)

When user data is available via _df.identify(), the following fields are SHA-256 hashed before sending to Microsoft:

Event Mapping

Example: Purchase Event

Datafly.js call:

_df.track("Order Completed", {
  order_id: "ORD-001",
  total: 129.99,
  currency: "USD",
  products: [
    { product_id: "SKU-A", name: "Widget", price: 49.99, quantity: 2 },
    { product_id: "SKU-B", name: "Gadget", price: 30.01, quantity: 1 }
  ]
});

Microsoft Ads CAPI payload sent by Signal:

{
  "customer_id": "123456789",
  "account_id": "987654321",
  "uet_tag_id": "12345678",
  "event_type": "Purchase",
  "event_time": "2024-01-29T12:00:00Z",
  "event_id": "evt_abc123def456",
  "click_id": "abc123def456ghi789",
  "revenue": 129.99,
  "currency_code": "USD",
  "transaction_id": "ORD-001",
  "page_url": "https://example.com/checkout/confirmation",
  "user_agent": "Mozilla/5.0 ...",
  "ip_address": "203.0.113.50"
}

Testing Your Integration

Step 1: Enable UET Tag Helper

1. Install the UET Tag Helper browser extension from the Microsoft Edge Add-ons store (also available for Chrome).
2. Navigate to your website and trigger events.
3. The extension will show whether UET events are being received (note: this only validates client-side tags, but can confirm your conversion goals are configured correctly).

Step 2: Verify via Signal Event Debugger

1. Trigger events on your website with the Signal integration enabled.
2. Open the Signal event debugger to confirm events are being delivered.
3. Verify the delivery status shows 200 OK responses from Microsoft.

Step 3: Check in Microsoft Advertising

1. In Microsoft Advertising, go to Tools > Conversion tracking > Conversion goals.
2. Check the Tracking status column — it should show “Recording conversions” or “Tag active”.
3. Click on individual goals to see conversion counts. Allow up to 4 hours for data to appear.

Troubleshooting

Rate Limits