> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/connectors/destinations/microsoft-advertising.md).

# Microsoft Advertising

Send offline data to Microsoft Ads Customer Match audiences.

The Microsoft Advertising connector sends offline data from mediarithmics to [Microsoft Ads Customer Match](https://help.ads.microsoft.com/apex/index/3/en/56921) audiences.

<table data-search="false"><thead><tr><th width="220">Connection</th><th></th></tr></thead><tbody><tr><td><strong>Type</strong></td><td>Server-side</td></tr><tr><td><strong>Category</strong></td><td><a href="/connectors/partner-types/dsp.md">DSP</a></td></tr><tr><td><strong>Identifiers sent</strong></td><td>Email identifiers (SHA-256) only</td></tr><tr><td><strong>Authentication</strong></td><td>Microsoft OAuth on an individual admin account</td></tr></tbody></table>

## Description

### What you can do with this connector

* Build a Microsoft Ads Customer Match audience from a mediarithmics segment.
* Enrich a Customer Match audience that already exists.
* Set how long a user is retained in the Microsoft audience.

### Which identifiers are sent

* **Email identifiers**, SHA-256 encrypted. This connector sends nothing else.

## Connector setup

### Prerequisites

{% hint style="warning" %}
**Before your first feed:** you must already have created **one customer list audience** in the Microsoft Advertising UI and accepted the terms and conditions. The initial customer list does not need to contain any customer data, but **I ACCEPT** must have been selected. Doing so confirms you can lawfully disclose audience details - which are personal data - to Microsoft, and accepts the Customer Match Terms, the Microsoft Advertising Agreement and the Microsoft Advertising policies. Without it, customer list data cannot be uploaded through the Bulk API.
{% endhint %}

* A Microsoft Ads **admin account** with all the accesses needed on the account ID you are targeting.
* Your **Microsoft Advertising Account ID**.

{% hint style="warning" %}
**The whitelisting is tied to one individual Microsoft account on your side.** That account must hold admin roles on the advertising accounts you want to push data to. If it is deleted - when someone leaves the company, for instance - or loses its admin roles, Microsoft Ads stops allowing the data push.
{% endhint %}

### Authentication

{% hint style="info" %}
Coordinate with your account manager so you can hand over the authorisation code quickly. **The code expires after a few minutes.** You can regenerate one by repeating the steps.
{% endhint %}

### Setup steps

{% stepper %}
{% step %}
**Sign in with a Microsoft Ads admin account holding all the accesses needed on the target account ID.**

Also make sure you are logged in to the mediarithmics platform, since that is where you will be redirected.
{% endstep %}

{% step %}
**Open the authorisation URL.**

<a href="https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=a9f41a24-19d1-4cbf-9b30-d8e9a6f9a464&#x26;response_type=code&#x26;redirect_uri=https://navigator.mediarithmics.com/&#x26;response_mode=query&#x26;scope=openid%20offline_access%20https%3A%2F%2Fads.microsoft.com%2Fmsads.manage&#x26;state=12345&#x26;prompt=consent" class="button secondary" data-icon="arrow-up-right-from-square">Open authorisation URL in a new tab</a>
{% endstep %}

{% step %}
**Click Accept.**

You are redirected to the mediarithmics platform.
{% endstep %}

{% step %}
**Copy the URL you land on.**

It carries an authorisation code as a query parameter.
{% endstep %}

{% step %}
**Give the code value, or the complete URL, to your CSM or Solution Architect - along with the Microsoft Advertising Account ID.**
{% endstep %}

{% step %}
**Create the feed and fill in its configuration.**

<table data-search="false"><thead><tr><th width="400">Field</th><th></th></tr></thead><tbody><tr><td><strong>Name</strong></td><td>Identifies the feed in mediarithmics.</td></tr><tr><td><strong>Microsoft Advertising Account ID</strong></td><td>The advertising account to sync the audience with. It must have been set up beforehand.</td></tr><tr><td><strong>Microsoft Audience Name</strong> <em>(optional)</em></td><td>A specific name for the Customer Match list. Defaults to the mediarithmics segment name.</td></tr><tr><td><strong>Microsoft Audience Description</strong> <em>(optional)</em></td><td>A specific description for the Customer Match list.</td></tr><tr><td><strong>Microsoft Advertising audience related customer list ID</strong> <em>(optional)</em></td><td>An existing Customer Match audience to enrich. Only audiences in the selected Microsoft Ads account are listed.</td></tr><tr><td><strong>Retention (in days)</strong> <em>(optional)</em></td><td>Days before a user is expunged from the segment in Microsoft Advertising. Default <code>-1</code>, meaning never.</td></tr></tbody></table>
{% endstep %}
{% endstepper %}

Creating and activating the feed on a segment is covered in the **Audience & Activation** section, under *Activate your audiences › Send your first-party data to a destination*.

## Good to know

[Your segment must contain at least **300 users**](https://help.ads.microsoft.com/apex/index/3/en/56921) to create a Customer Match audience and target across the Microsoft Advertising Network.

## FAQ

#### How do I check the Microsoft Ads audience details and match rate?

1. Open the segment linked to your feed.
2. Scroll to the **Feeds** section.
3. Select **Troubleshooting** in the options of the Microsoft Ads feed card.
4. Scroll to **Audience description on the destination platform**.

It shows the destination audience metadata, the audience network and search sizes, and the supported campaign types.

#### The upload fails on a brand new account. Why?

Because no customer list audience has been created and accepted in the Microsoft Advertising UI yet. Create one - it can be empty - and select **I ACCEPT**.

#### Our data push stopped working. Nothing changed on our side.

Check the Microsoft account used for the whitelisting. If it was deleted, or lost its admin roles, Microsoft Ads blocks the push.

## Partner documentation

Microsoft Advertising documents its own platform at <https://help.ads.microsoft.com/>. Use it for anything that happens on the partner side of this connector: account setup, the fields the partner expects, and its own limits.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mediarithmics.io/connectors/destinations/microsoft-advertising.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.