Microsoft Ads

Overview

This source syncs performance reports from the Microsoft Advertising API (Bing Ads API v13) using the official bingads Python SDK. Reports are requested asynchronously: the connector submits a report request, polls until the result is ready, downloads the data, and emits one record per row. The three performance-report streams use daily aggregation by default and sync incrementally on TimePeriod per ad account, so only new or updated days are fetched on subsequent runs. The ad_labels stream is a full-table stream built from current Campaign Management ad label associations. Authentication uses OAuth 2.0 with a refresh_token (no service accounts). You provide an Azure AD application’s client_id (and optionally client_secret) alongside a developer_token that identifies your API application.

Configuration

Key	Required	Default	Description
`developer_token`	✅	—	Microsoft Advertising developer token. Identifies your application to the API. Obtained from Microsoft Advertising API Center.
`client_id`	✅	—	Azure AD Application (client) ID for your registered app.
`client_secret`		—	Azure AD client secret. Required for confidential/web app OAuth flows. Leave empty for public/desktop app flows.
`refresh_token`	✅	—	OAuth refresh token scoped to `https://ads.microsoft.com/msads.manage`. See Authentication with OAuth.
`oauth_redirection_uri`		`https://login.microsoftonline.com/common/oauth2/nativeclient`	Redirect URI registered in Azure AD. Must match the URI used when obtaining the refresh token. Required when `client_secret` is set.
`customer_id`	✅	—	Microsoft Advertising manager account (customer) ID the user operates under.
`account_ids`	✅	—	Comma-separated advertiser account IDs to sync. Find these in the Microsoft Advertising UI under account settings.
`start_date`	✅	—	Reporting lower bound. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`).
`end_date`		today (UTC)	Optional reporting upper bound.
`insights_lookback_window`		`0`	Days to rewind from the saved report bookmark when syncing performance reports. Never goes earlier than `start_date`.
`ad_labels_max_ads`		`10000`	Maximum current ads to scan per account when syncing `ad_labels`; increase only when large-account sync time and API quota are acceptable.
`ad_labels_max_hierarchy_requests`		`1000`	Maximum campaign/ad group/ad hierarchy API requests per account when syncing `ad_labels`.
`environment`		`production`	API environment: `production` or `sandbox`.
`aggregation`		`Daily`	Report aggregation period. Common values: `Daily`, `Weekly`, `Monthly`.
`report_time_zone`		—	ReportTimeZone value. Leave empty to use the account’s default time zone.
`poll_interval_ms`		`5000`	Milliseconds between status polls while the async report is generating.
`report_timeout_ms`		`3600000`	Maximum milliseconds to wait for report download before failing (default 1 hour).

Legacy key: accounts is accepted as an alias for account_ids for backwards compatibility.

Sample configs

Minimal — production environment, daily reports:

developer_token: YOUR_DEVELOPER_TOKEN
client_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
refresh_token: YOUR_REFRESH_TOKEN
customer_id: "12345678"
account_ids: "111111111,222222222"
start_date: "2025-01-01T00:00:00Z"

Confidential app flow (with client secret):

developer_token: YOUR_DEVELOPER_TOKEN
client_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
client_secret: YOUR_CLIENT_SECRET
refresh_token: YOUR_REFRESH_TOKEN
oauth_redirection_uri: https://login.microsoftonline.com/common/oauth2/nativeclient
customer_id: "12345678"
account_ids: "111111111"
start_date: "2025-01-01T00:00:00Z"

Sandbox testing:

developer_token: YOUR_DEVELOPER_TOKEN
client_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
refresh_token: YOUR_SANDBOX_REFRESH_TOKEN
customer_id: "12345678"
account_ids: "111111111"
start_date: "2025-01-01T00:00:00Z"
environment: sandbox

Streams

Stream	Report type	Description
`campaign_performance_report`	CampaignPerformanceReportRequest	Daily campaign-level impressions, clicks, spend, and conversions.
`ad_group_performance_report`	AdGroupPerformanceReportRequest	Daily ad group-level performance metrics.
`ad_performance_report`	AdPerformanceReportRequest	Daily ad-level performance metrics.
`ad_labels`	Campaign Management label associations	Full-table rows for current ad label associations.

Performance report streams sync incrementally on TimePeriod (one bookmark per ad account). On the first run the full history from start_date is fetched; subsequent runs fetch only new or updated days. The ad_labels stream syncs as full table from the current label associations returned by the Campaign Management API.

How to get credentials

1. Developer token

Sign in to Microsoft Advertising as the account owner or a user with API access.
Go to Tools → API Center (or visit the Microsoft Advertising API Center directly).
Request and copy your developer token.

2. Azure AD app (`client_id` / `client_secret`)

Open Azure Portal → App registrations and click New registration.
Choose Public client / native for desktop flows (no client_secret required) or Web for server flows.
Add https://login.microsoftonline.com/common/oauth2/nativeclient as a redirect URI (or your own URI for web flows).
Copy the Application (client) ID → client_id.
For web flows: go to Certificates & secrets and create a client secret → client_secret.

3. Refresh token

Use the Microsoft Advertising OAuth guide to complete the authorization code flow with the scope https://ads.microsoft.com/msads.manage offline_access. Copy the resulting refresh_token into your config.

4. `customer_id` and `account_ids`

Find these in the Microsoft Advertising UI:

Customer ID — shown in the top-right account selector next to your account name.
Account IDs — visible in Accounts Summary or each account’s settings page.

Adventure starts here

Deployment architecture

Getting started

Mage Agent

CI/CD

Pro only features

Infrastructure

Migration guides

Global hooks

Mage Pro API

Overview

Configuration

Sample configs

Streams

How to get credentials

1. Developer token

2. Azure AD app (`client_id` / `client_secret`)

3. Refresh token

4. `customer_id` and `account_ids`

​Overview

​Configuration

​Sample configs

​Streams

​How to get credentials

​1. Developer token

​2. Azure AD app (client_id / client_secret)

​3. Refresh token

​4. customer_id and account_ids

​Related links

Overview

Configuration

Sample configs

Streams

How to get credentials

1. Developer token

2. Azure AD app (`client_id` / `client_secret`)

3. Refresh token

4. `customer_id` and `account_ids`

Related links