> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cometly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure the Microsoft Ads Conversion API

> Set up the Microsoft Ads Conversion API in Cometly to send your leads and sales to Microsoft Ads as offline conversions matched to the right ad click.

The Microsoft Ads Conversion API (CAPI) sends conversion events from Cometly directly to Microsoft Ads as offline conversions. An event is an action Cometly tracks, such as a lead or a purchase. With CAPI enabled, you map your Cometly events to Microsoft conversion goals, and Cometly sends matching conversions to Microsoft Ads automatically.

This gives Microsoft more complete data about how your ads perform, even when browser-based tracking (like the UET tag) misses events because of ad blockers, cookie restrictions, or cross-device behavior. Your Microsoft Ads reporting then shows the leads and sales Cometly tracked, next to the campaigns that produced them.

## Before you begin

You need:

1. **A connected Microsoft profile.** Sign in with Microsoft on Cometly's Integrations page so Cometly has permission to talk to your Microsoft Ads account (Step 1).
2. **A Microsoft ad account connected to your space.** The ad account you want to send conversions to must be connected to your current space (Step 2). A space is a Cometly workspace with its own settings, integrations and data.
3. **Offline conversion goals in Microsoft Ads.** CAPI sends data as offline conversions, so you need at least one offline conversion goal in your Microsoft Ads account (Step 3). Cometly loads these goals during configuration.

## Step 1: Connect your Microsoft profile

If you have not connected your Microsoft profile yet:

1. Click **Integrations** in the sidebar.
2. Under **Ad Platforms**, expand the **Microsoft Ads** row.
3. Click **Sign in with Microsoft**.
4. Complete the sign-in in the pop-up window.

Once connected, your Microsoft profile appears in the **Microsoft Ads** row.

## Step 2: Connect your ad account to your space

1. On the **Integrations** page, expand the **Microsoft Ads** row. You see a list of the ad accounts your profile can access.
2. Click **Connect & Sync Data** next to the ad account you want to use.

The account is now connected to your current space and ready for CAPI configuration.

## Step 3: Create offline conversion goals in Microsoft Ads

For every offline conversion you want to measure, create an offline conversion goal in Microsoft Ads. You can create as many as you need.

Auto-tagging of the Microsoft Click ID is turned on automatically when you create your first offline conversion goal. You can [check the auto-tagging status of the click ID](https://help.ads.microsoft.com/#apex/ads/en/60000/2) on the account-level options page.

1. From the navigation menu on the left, hover over **Conversions** and select **Conversion goals**.

2. Select **Create conversion goal** and select the **Offline conversions** type.

3. Enter a name for your goal in the **Goal name** box. Use a descriptive name that makes sense to you (for example, "Check-out page"). You cannot use the same name for two different conversion goals.

4. Under **Sharing**, select whether this goal applies to all accounts or a specific account.

5. If you want to add a monetary value for each conversion, under **Revenue value**, select one of these checkboxes:

   * **Each time it happens, the conversion action has the same value**. Enter the amount and select the currency, if available. This is a static value that doesn't change.
   * **The value of this conversion action may vary (for instance, by purchase price)**. Enter the default amount and select the default currency, if available, to be used when no value is received for a conversion.

6. You can also assign a **Count** to the conversion and enter a **Conversion window** to track up to 90 days in the past.

7. Select **Save**.

After you create a conversion goal, Microsoft prompts you to upload the conversions now or later. You do not need to upload anything yourself: Cometly sends the conversions.

According to the Microsoft Ads documentation, after you create a new conversion goal **you must wait 2 hours before conversions can be uploaded for it**.

When the offline conversion goal is created, the grid shows a dash ( - ) for **UET tag ID** and **Tracking status**, because UET tags aren't required.

## Step 4: Turn on the Microsoft Conversion API

1. In Cometly, click **Events Manager** in the sidebar, then open the **Conversion API** tab.
2. Click the **Microsoft** row to expand it.
3. Under **Manage data sharing**, select **Turn on data sharing**. The change is saved straight away.

The account picker and the mapping table appear once data sharing is on.

## Step 5: Map your events to conversion goals

This is the most important step. You tell Cometly which of your events to send to Microsoft, and which Microsoft conversion goal each one belongs to.

1. Under **Microsoft Advertising account**, select the ad account.

2. Cometly loads the offline conversion goals from that account and lists them under **Microsoft conversion goals**.

3. For each conversion goal you want to receive data:

   * Under **Cometly events**, select the event that should trigger this conversion (for example Purchase, Lead, or any custom event you've created).
   * Under **Rule**, choose one of:
     * **Send all events.** Every time this Cometly event fires, it is sent to Microsoft regardless of which ad platform gets the attribution.
     * **Only send attributed events.** The event is sent only if Cometly attributed the conversion to this Microsoft ad account. This is the more conservative option and avoids inflating your Microsoft conversion counts.

   ![Expanded Microsoft row on the Conversion API tab with Turn on data sharing selected, an account chosen under Microsoft Advertising account, and a Lead conversion goal mapped to the Lead event with the rule Only send attributed events, above the Save button](https://mintcdn.com/cometly/BM7eSn6-ecx8ZzBx/images/guides/conversion-api/microsoft/01.webp?fit=max\&auto=format\&n=BM7eSn6-ecx8ZzBx\&q=85\&s=5f0570f2c933747e2b03b35008a7d822)

4. Click **Save**.

You can map several conversion goals per account, each to a different Cometly event. Map each Cometly event to one goal per account: if the same event is mapped to two goals in one account, only one of them receives the conversion. You can map the same event again in another connected Microsoft ad account.

## Check it worked

On the **Conversion API** tab, the **Microsoft** row now shows the **Active** badge, and your mapping is listed under **Microsoft conversion goals**. From here, Cometly sends each mapped conversion about 15 minutes after the event is tracked. Microsoft Ads can take up to 24 hours to process offline conversions before they show in its reporting.

## What data gets sent to Microsoft

When a mapped event fires and CAPI is on, Cometly sends this data to Microsoft Ads:

| Data | Description |
| - | - |
| **Conversion goal name** | The name of the mapped Microsoft conversion goal |
| **Conversion time** | The timestamp of the event (UTC) |
| **Conversion value** | The monetary value of the event (if available) |
| **Currency code** | Your space's currency, sent together with the value |
| **Microsoft Click ID (msclkid)** | The click identifier from the original ad click (if available) |
| **Hashed email** | SHA-256 hashed, normalized email address (if available) |
| **Hashed phone number** | SHA-256 hashed, normalized phone number (if available) |

Cometly normalizes and hashes personal data before sending. Microsoft needs at least one identifier (msclkid, email, or phone) to accept the conversion.

## Turn CAPI off

To disable the Microsoft Conversion API:

1. Click **Events Manager** in the sidebar and open the **Conversion API** tab.
2. Expand the **Microsoft** row.
3. Select **Turn off data sharing**.

No events are sent to Microsoft while CAPI is off. Your event mappings are kept, so you can turn it back on at any time without reconfiguring.

## Troubleshooting

If conversions aren't appearing in Microsoft Ads, check the following:

* **Is CAPI turned on?** The **Microsoft** row on the Conversion API tab should show the **Active** badge, with **Turn on data sharing** selected.
* **Is the event mapped?** Make sure the Cometly event that fires is mapped to a Microsoft conversion goal.
* **Are identifiers present?** Microsoft needs at least one of msclkid, email, or phone number. A conversion with none of these cannot be matched.
* **Is the account active?** Make sure the Microsoft ad account is still connected and active in your space.
* **Are you using "Only send attributed events"?** With this rule, the event is not sent when Cometly did not attribute the conversion to that Microsoft account. Switch to "Send all events" to test.
* **Does the conversion goal still exist in Microsoft Ads?** The offline conversion goal must exist in your Microsoft Ads account. Cometly sends conversions by goal name, so if the goal was deleted or renamed on the Microsoft side, the mapping fails. Reload the mapping in Cometly and save it again.

## Frequently asked questions

### Do I need a UET tag if I use the Microsoft Ads Conversion API?

No. CAPI works independently of the UET tag. However, Microsoft recommends using both together for the most complete tracking coverage.

### How quickly do conversions appear in Microsoft Ads?

Cometly sends each conversion about 15 minutes after the event is tracked. Microsoft Ads then takes time to process and display offline conversions in its reporting. This is controlled by Microsoft, not Cometly, so expect up to a 24 hour delay.

### Is personal data shared with Microsoft?

Email addresses and phone numbers are normalized and hashed (SHA-256) before being sent. Cometly never sends raw personal data to Microsoft.

## Next steps

* [Connect and manage the Microsoft Ads integration](https://docs.cometly.com/integrations/ad-platforms/microsoft.md)
* [Set up the Conversion API for your other ad platforms](https://docs.cometly.com/guides/conversion-api/overview.md)
* [Exclude an event from the Conversion API](https://docs.cometly.com/guides/conversion-api/exclude-an-event.md)
* [Learn how Cometly events work](https://docs.cometly.com/guides/events/how-events-work.md)
* [Troubleshoot a Microsoft Ads connection](https://docs.cometly.com/support/troubleshooting/ad-data/microsoft-ads-connection.md)

Still have questions or need a hand? We're happy to help. Reach our team at [support@cometly.com](mailto:support@cometly.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.