Skip to content
adscapi
← Platforms
Real Conversions API

Bing (Microsoft Ads) setup

Set Bing (Microsoft Ads)’s tokens once. Then every ads.conversions.track() call fans the event out to Bing (Microsoft Ads) server-side — no per-platform code.

Setup guide

Overview

adscapi sends server-side conversions to the Microsoft Advertising UET endpoint (GET https://bat.bing.com/action/0). This is the same endpoint the browser UET tag (bat.js) posts to, fired from your server. The request carries no auth token and no hashed PII. It is keyed by your UET tag id (ti). When the event has a Microsoft click id (clickIds.msclkid), adscapi forwards it as msclkid for click-level attribution. Without a click id the event still fires — UET records it, just with weaker attribution.

Prerequisites

  • A Microsoft Advertising account.
  • Auto-tagging enabled (the default), so ad landing URLs carry msclkid=….

1. Create a UET tag

  1. Sign in to Microsoft Advertising.
  2. Go to Tools → UET tag and create a tag, or reuse an existing one.
  3. Copy the tag id. It is the numeric ti value in the bat.js snippet (for example ti="12345678").

2. Get your credentials

Secret Where to get it
BING_UET_TAG_ID The UET tag id from Tools → UET tag (the ti value in the snippet).

No token is required — the endpoint is unauthenticated and keyed by the tag id.

Capture the click id: Microsoft appends msclkid=<click_id> to your ad landing URLs. Read it on arrival, persist it against the session/user, and pass it on the event as clickIds.msclkid. adscapi sends it unhashed.

3. Configure adscapi

export BING_UET_TAG_ID="…"   # numeric UET tag id (the ti value)

4. Verify

There is no live verify check for bing: the endpoint accepts any well-formed GET, so there is no cheap authenticated call that proves the tag id. Send a test event and confirm it under Tools → Conversion goals:

adscapi test-event --event purchase --value 5 --currency usd --dry-run

5. Event mapping

Canonical UET
page_view evt=pageLoad
everything else evt=custom, ea=<canonical name>

bing ships an empty event-name map on purpose. The canonical name passes through as-is and becomes the event action label (ea). For custom events, create a conversion goal in Microsoft Advertising whose event-action value matches that name. ec is always adscapi; el carries your transactionId when present.

Revenue: send both value and currency. adscapi maps them to ev/gv and an uppercased gc.

Troubleshooting

  • No conversions appear — no conversion goal matches the event action label. Create a custom-event goal whose action value equals the canonical name you send.
  • Weak attribution — clickIds.msclkid is missing. Capture msclkid from the ad landing URL and carry it to your backend.
  • Event not sent at all — consent is off. adscapi no-ops unless adUserData or adPersonalization consent is set.
  • Offline conversions — this integration is the UET server pixel. The ApplyOfflineConversions offline-upload API is a separate path and not yet supported.

1. Install adscapi

shell
npm install adscapi
# or run without installing:
npx adscapi platforms

2. Get Bing (Microsoft Ads)'s tokens

Bing (Microsoft Ads) activates once all of these are set. Run npx adscapi platforms to see them, then get each value from Bing (Microsoft Ads)’s ads or events dashboard.

BING_UET_TAG_ID

3. Set them for adscapi

Export the tokens in the environment that runs your server or the adscapi CLI.

shell
export BING_UET_TAG_ID="…"

4. Verify

check confirms the secrets are present; verify calls Bing (Microsoft Ads)’s API to confirm they are valid.

shell
npx adscapi check
npx adscapi verify --platform bing

5. Track a conversion

One call, sent to Bing (Microsoft Ads) and every other configured platform. Pass raw email — adscapi hashes per platform. Consent is required.

ts
import { createAdscapi } from 'adscapi';

const ads = createAdscapi();

const results = await ads.conversions.track({
  name: 'purchase',
  value: 49,
  currency: 'USD',
  user: { email: 'buyer@example.com' },
  consent: { adUserData: true, adPersonalization: true },
});

See the exact request on the Bing (Microsoft Ads) payload preview.