A customer can complete a purchase without the sale appearing in Microsoft Advertising. A demo request might turn into a qualified opportunity weeks after the ad click, long after the visitor has left the website. Browser tracking captures the initial activity but cannot always follow the outcome into a sales system.
Microsoft Advertising Conversions API (CAPI) gives advertisers a server-to-server way to send eligible conversion events from a website backend, CRM, or another connected system. Microsoft announced general availability on October 28, 2026. The benefit is a clearer view of business outcomes that browser tracking may miss, not a guarantee that Microsoft will attribute every submitted event to an ad.
Microsoft conversions API setup involves choosing meaningful events, coordinating CAPI with Universal Event Tracking (UET), preventing duplicates, and testing attribution. Getting those steps right matters more than simply increasing the volume of reported events.
What Is Microsoft Advertising Conversions API?
CAPI receives conversion events directly from systems such as order databases and CRMs. An ecommerce store might report a purchase after payment clears; a B2B team could send a qualified-lead event after a salesperson reviews the inquiry. These events describe business outcomes rather than page views alone.
Microsoft introduced the feature in its October 2026 product announcement as another source of first-party signals for attribution and optimization. An accepted event does not prove that Microsoft can attribute it to an ad. The platform still needs suitable identifiers, a matching conversion goal, an eligible event time, and the applicable attribution conditions.
Microsoft CAPI vs. UET Tracking
UET is Microsoft’s browser-side tag for website events and audience signals. CAPI sends events from a server or connected business system. Microsoft recommends using both when practical: UET provides browser context, while CAPI can report outcomes that happen after the visitor leaves the site.
For example, UET might record a checkout completion and CAPI might report the same confirmed purchase. Both paths need matching event details so Microsoft can recognize them as one purchase. A qualified lead created later in the CRM, on the other hand, may be a separate conversion with no browser duplicate. Confirm which conversion goal will recognize each signal before revising the existing tracking setup.
The Universal Event Tracking documentation explains website conversion goals and remarketing. CAPI does not automatically replace those functions. Review the current UET goals and audience setup before changing the browser tag; removing a working tag can discard signals that the server integration does not supply. Neither method removes consent requirements or grants permission to collect and transmit data that the business should not share.
When Microsoft Ads Server-Side Tracking Makes Sense
Microsoft Ads server-side tracking is most useful when browser events miss a valuable result. A store may want confirmed orders rather than an incomplete checkout signal. A service company may care about booked appointments; a B2B team may value sales-qualified opportunities more than raw forms. CAPI can connect those later actions to the advertising system when appropriate matching information exists.
Begin with one question: which outcome matters to the business but currently has weak or no Microsoft Ads measurement? That answer shapes the event specification, source system, and integration effort. Advertisers already using a CRM should also distinguish CAPI from a platform-specific Microsoft Ads and HubSpot integration. A HubSpot connector may cover a specific contact workflow without supporting every CAPI event type.
A site with reliable UET purchase tracking may not need another pipeline immediately. Server connections require maintenance, monitoring, privacy controls, and a plan for failed requests. Before committing engineering time, weigh the value of missing conversion signals against the cost of maintaining a secure integration. For a small team, one dependable qualified-lead event may be more useful than a complicated feed of every CRM stage.
How to Set Up Microsoft Advertising Conversions API
Choose an integration route based on where the event originates and who can maintain it. A direct API suits custom systems; a partner connector may reduce development work; a server-side tagging setup can fit an existing measurement architecture. Whatever the route, the advertiser needs control over account access, event definitions, and the troubleshooting process.
| Setup Path | Best Fit | Main Check |
|---|---|---|
| Direct API | Custom backend or CRM | Developer handles authentication, validation, retries, and logs |
| Partner integration | Supported CRM or data platform | Connector sends the intended event stages and identifiers |
| Server-side tagging | Existing tag-management architecture | Events reach the server endpoint without duplicate browser copies |
Document the complete path from the business action through the source application and sending service to Microsoft and the conversion goal. Name an owner for each step and a way to inspect failures. This map is more useful during troubleshooting than a vendor dashboard that only says the connection is active.
1. Define Conversion Events and Goals
Start with a specific action: confirmed purchase, qualified consultation, accepted lead, or closed sale. Decide which Microsoft Advertising goal should recognize it and whether another goal already counts the same business result. A CRM status change is not automatically a new sale.
Document the event name, trigger, source of truth, stable event ID, timestamp, available attribution identifiers, and value or currency where applicable. Have marketing and engineering approve the same definition. Resolve disagreements about the event definition before the integration sends production data. If an order can change state after checkout, decide whether refunds and cancellations belong in the source event or need a separate reporting treatment. Keep those rules consistent with how finance and sales teams define the result.
2. Confirm the UET Tag, CAPI Token, and Connection
Match the connection to the correct Microsoft Advertising account and UET tag. The direct API uses an authorization token associated with that tag; keep it out of public pages, client-side code, and public repositories. Restrict access and plan how to replace an exposed token.
Microsoft’s Conversions API implementation reference describes token retrieval, payload fields, and the endpoint. The interface flow includes editing the UET tag, choosing Save and next, and selecting Use Conversions API to obtain the token. Confirm the current steps in your account, particularly when a partner manages the connection.
Microsoft CAPI with Google Tag Manager requires a clear distinction between browser tags and server-side requests. A trigger in a web container does not by itself create a server-to-server connection. Identify the sending service and who handles failed requests.
3. Map Events and Matching Identifiers
The API uses eventType values such as custom and pageLoad. For custom events, map eventName and a stable eventId; supply eventTime as a Unix UTC timestamp in seconds. The userData object must contain at least one supported matching identifier. Where relevant, send the business value, currency, or transaction reference in customData.
An internal order number alone does not meet the matching requirements. Capture permitted identifiers, including the Microsoft Click ID (msclkid) when available, and preserve them through forms and CRM records as appropriate. Follow Microsoft’s field-format and hashing rules: email and phone fields that expect hashes require correctly formatted SHA-256 values. Do not insert raw contact details into hashed fields.
4. Test Delivery, Matching, and Attribution
Send controlled events that correspond to records you can inspect. Check API responses, warnings, rejected fields, timestamps, IDs, and the intended conversion goal. Then test whether Microsoft attributes an eligible event. An HTTP 200 response may indicate partial processing; it does not guarantee acceptance of every event or advertising attribution. Inspect the response body for rejected records and field-level warnings.
Maintain a log that links the business record to the send status and observed reporting result. Check consent handling as well. Microsoft treats omitted adStorageConsent as granted; D (denied) prevents the event’s use for advertising attribution or retargeting. Set the signal to reflect actual choices, and follow applicable privacy requirements.
How Microsoft Ads Event Deduplication Works
Running UET and CAPI together can produce two copies of the same purchase. If each path assigns a different identity, Microsoft may treat them as separate conversions and distort the data that guides bidding. This is why Microsoft Ads event deduplication belongs in the initial design, not in post-launch cleanup.
The Microsoft Conversions API event ID (eventId) must match the UET browser parameter event_id for the same conversion. Keep the UET tag ID and eventName consistent across both routes. Generate the ID when the business action occurs, and preserve it across retries. A new ID for each retry can turn one purchase into several apparent events. Record the ID with the original order or conversion record, not just in a temporary request log. Otherwise, an outage or queue restart can quietly create duplicates even when normal tests pass.
Do not reuse that ID for genuinely different actions. A form submission and a lead that the sales team qualifies two days later represent different stages even when they belong to one person. If conversion totals rise sharply after CAPI goes live, check duplicate IDs before crediting the campaign with an improvement. Avoid changing these measurement definitions midway through Microsoft Advertising optimization experiments, when consistent comparison matters.
MSCLKID, ID Sync, and the 90-Day Limit
When auto-tagging is active, msclkid can identify a Microsoft advertising click. Capture it on eligible landing-page visits and pass it into later event records where appropriate. Test redirects, forms, booking systems, and CRM integrations; a lost URL parameter can break matching without affecting the customer’s visible experience. Start with a controlled tagged click, trace the identifier through a test form, and inspect the CRM record before sending the corresponding conversion. Do the same after a website or form-provider migration. A successful form submission says nothing about whether the tracking value survived.
Microsoft accepts CAPI events with timestamps from the preceding 90 days. Its guidance also discusses retaining the latest click ID for up to 90 days where appropriate. Replace an older stored msclkid when a newer one arrives, and pass the click ID without hyphens. Use the original business event time, not the time a batch job uploads the record.
These rules do not promise 90 days of attribution. A valid event may still fall outside the conversion goal’s attribution window. Microsoft documents the account-level setting in its auto-tagging reference.
Microsoft also describes browser-based ID Sync, which connects an advertiser visitor ID to Microsoft identifiers. Microsoft requires client-side ID Sync for dynamic remarketing and recommends it to improve conversion matching where applicable. The CAPI anonymousId must align with the identifier used in that sync. A server request alone does not perform the browser-side synchronization.
CRM Leads vs. Microsoft Ads Offline Conversions
For CRM events, define stages before mapping fields. Form submissions, sales-accepted leads, and completed sales represent different outcomes. The useful signal depends on how often each stage occurs, its business value, and whether sales staff apply the definition consistently.
A CRM pipeline needs stable timestamps and event identifiers. Otherwise, routine edits can generate duplicate conversion messages. Keep the record of when a lead first reached a stage separate from the date of its most recent edit. B2B teams should connect the selected stage to their actual qualification process, as discussed in Microsoft Ads for B2B lead generation. Choose a stage with enough volume and consistency to support meaningful decisions. If two sales reps use the same status differently, fix the CRM workflow before feeding that status into bidding.
Traditional offline conversion uploads remain a separate Microsoft Ads workflow. Their goal setup and duplicate-handling rules differ from CAPI’s shared browser/server eventId: traditional offline imports use click identifiers and conversion times, subject to the goal’s count settings. Before migrating, choose one route for each business event and verify that overlapping methods will not count it twice.
Microsoft Conversions API Troubleshooting
Separate four questions during troubleshooting: did the server send the record, did Microsoft accept its fields, could it match the event, and did a conversion goal attribute it? Skipping those distinctions leads teams to reinstall an integration when the real problem is a missing click ID or an ineligible goal.
| Symptom | Possible Cause | First Check |
|---|---|---|
| HTTP 401 | Invalid or unauthorized token | Token, UET tag ID, Bearer authorization |
| HTTP 400 | Payload validation problem | Field name, event type, timestamp, failed record |
| HTTP 200 but no conversion | Event accepted without attribution | Goal mapping, matching ID, attribution window |
| Conversions jump unexpectedly | UET and CAPI duplicates | Shared eventId, tag ID, and event name |
| CRM events lack attribution | Missing or lost identifiers | Landing-page-to-CRM data flow |
| Remarketing sync fails | ID Sync or visitor-ID mismatch | Browser sync and anonymousId alignment |
Inspect field-level warnings even when Microsoft accepts an event. An invalid optional identifier may weaken matching without causing the whole request to fail. The API accepts up to 1,000 events per batch. By default, a validation error can reject the entire batch; continueOnValidationError lets Microsoft process valid records while reporting rejected ones. Log those failures, correct their fields, and preserve the original event IDs when resending. Monitor accepted, rejected, and attributed events separately. If API traffic looks healthy while conversions remain flat, investigate matching and goal configuration before replacing the connection.
What CAPI Cannot Fix on Its Own
CAPI cannot invent an advertising click, correct inconsistent CRM stages, override consent, or guarantee agreement between a sales database and an ad platform. The CRM may record every sale while Microsoft reports only conversions that meet its attribution rules. That difference can be legitimate even when both systems work as intended.
Start with one valuable event. Map its identifiers, test delivery and attribution separately, and verify deduplication before using the new signal to change bidding. Microsoft Advertising Conversions API can improve measurement, but its value depends on the quality of the business event and the evidence that the platform interprets it correctly.